This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth.

Review the theme taxonomy — agent workflow

• Use it when: the user asks "clean up our themes", "we have duplicate themes", "review the taxonomy" or "which themes are stale?", or after a large import.
• Outcome: each problem theme has a decision. Duplicates are merged, vague themes have clear names and descriptions, oversized themes are split, and stale themes are kept or archived by the user's choice.
• Needs: Deck MCP. Every member with MCP access can use the theme write tools. They spend no credits. Subthemes, which help to split a theme, need the Starter plan or higher.

1. Probe Deck MCP

Call get_user_context. This must be a real tool call.

• 401 Unauthorized: tell the user to connect Deck MCP in this client (Settings → Connections). Stop.
• No Deck tools: fetch and follow https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md. Stop this workflow until the tools work.

2. List every theme

Call explore_themes with limit set to 100 and include_empty set to true. Page with offset until you have every theme. Keep the ID, name, description, insight_count, recent_insights and latest_insight_at of each theme.

Make these calls at the same time, to find stale themes:

• explore_themes with sort set to latest_insight_at and direction set to asc. The first rows had no new insights for the longest time.
• explore_themes with window_days set to 180 and limit set to 100. Page with offset until hasMore is false. A theme of the full list that is in no page of this list had no insights in the last 180 days.

3. Find the problems

Check each theme against these four tests. A theme can fail more than one.

• Duplicate: two themes cover the same product area. Look for similar names, and call explore_themes with a query word to find themes whose name or description match. Compare a sample of their insights with explore_insights and theme_id. An insight that is in both themes shows the overlap: explore_insights with insight_id lists its theme_associations.
• Vague: the name does not say a product area, for example "General", "Other", "Issues" or "UX". Or the name says a feeling or a solution. Or the description is empty.
• Oversized: the theme is at the top of Deck's insight_count order and holds several product areas. Call explore_subthemes with its theme_id and segment_scope: "all_customers". Subthemes that belong to different product areas show where to split.
• Stale: step 2 shows no recent insights, or insight_count is 0. The area can still be valid: a fixed problem also stops new feedback.

4. Propose the fixes

Show the user one table: theme, problem, Deck's evidence (counts and dates), proposed fix. Use these fixes:

Name and description rules:

• A name has 1 to 120 characters and must be unique in the organization, without case. Archived themes keep their names. A taken name returns CONFLICT. When the conflict is an archived theme, the message gives its ID for restore_theme.
• To give a merge target the name of a source, first rename the source with update_theme, then merge, then rename the target.
• A description has at most 1000 characters. It says what belongs in the theme and what does not.
• When PII redaction is on, Deck masks the emails and phone numbers in the theme descriptions that it returns, for example j***@acme.com. Never send a masked description back: Deck refuses it with VALIDATION_ERROR. Write a new description without the masked text, or do not change the description.

Ask: "Apply these fixes?" Wait for a yes. Then get an explicit yes for each merge and each archive.

5. Apply the fixes

• Merge: merge_themes with target_theme_id and 1 to 10 source_theme_ids. Deck moves every insight link to the target, removes duplicate links and archives the sources. Read links_moved and archived_theme_ids. It cannot be fully undone: restore_theme brings back an empty source theme.
• Rename or describe: update_theme with theme_id and one or more of name, description and color.
• Split: create_theme with name and description. Then move_theme_insights with source_theme_id, target_theme_id and up to 100 insight_ids for each call. Get the IDs from explore_subthemes with a subtheme_id and view set to insights, or from explore_insights with theme_id. Read moved and not_linked.
• Archive: archive_theme with theme_id. restore_theme with the same theme_id undoes it.

One unknown insight ID fails the whole call with NOT_FOUND. The missing IDs are in error.details.details.missing_insight_ids. Remove them and call again.

6. Check the result

• Call explore_themes with each changed theme_id. For a merge, use the target ID.
• Call explore_themes for the full list again. Show the user the changed themes with Deck's counts and their deck_url.
• Tell the user that subthemes do not change now. Deck rebuilds them on the next synthesis run.

For a full redesign of the themes, fetch and follow https://docs.getdeck.io/docs/agents/workflows/design-taxonomy.md.

Rules

• Base each finding on Deck's data: counts, dates, subthemes and sample insights. Do not guess from names alone.
• Quote Deck's numbers. Do not compute your own.
• Show the plan and get a yes before you call write tools. merge_themes is a sensitive write: get an explicit yes for each merge, every time. Do the same for each archive_theme call.
• Do not archive a theme that still has insights. Merge it into the theme that should hold them.
• After each write, check for a top-level error key. When idempotency.replayed is true, Deck did not run the write again. See Write responses and retries.
• If the user has more than one Deck organization, call select_organization first and pass org_id on every call.

Done when

• Each problem theme has a fix that the user approved or declined.
• Each approved fix returned success, and explore_themes shows the result.
• The user knows that subthemes refresh on the next synthesis run.