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

Design the theme taxonomy — agent workflow

• Use it when: the user asks "set up our themes", "make Deck's themes match our product areas", "our themes are a mess, start over" or "build a taxonomy from our feedback".
• Outcome: Deck's active themes match a taxonomy that the user approved. Each theme has a plain product-area name and a description that says what belongs in it. The insights sit in the right themes.
• Needs: Deck MCP, and customer feedback that is already in Deck. Every member with MCP access can use the theme write tools. They spend no credits. Subthemes 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. Gather the product context

Make these calls at the same time:

• get_overview: read organization.product_information, company_information, target_audience and keywords, and the theme and feedback counts in summary.
• explore_workspace with view set to settings: read your role and which features are on.

Then collect the product areas in the team's own words:

• If this session has the codebase, read the main routes, the navigation labels, the top-level modules and the product docs.
• If you have your own Linear or Jira tools, list the team, project and component names. Without them, list_projects with importable_from set to linear or jira lists the Linear projects or Jira epics of a connected workspace.
• Call list_initiatives and list_projects to see the names the team already uses in Deck.

When summary shows no feedback, stop. No MCP tool imports customer feedback. Tell the user to upload files in the Deck web app (CSV import, user interviews) or to ask an organization admin to connect an integration in Settings → Integrations.

When product_information is empty, ask the user for the main product areas. An organization admin can add it in Settings → Context (Product context). Deck's agents use it to map new feedback.

3. Read the current themes

• 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 and insight_count of each theme.
• Call explore_themes with view set to categories. It shows which categories, such as bugs or feature requests, hold the most insights, and their top themes.

4. Sample the feedback

Read enough feedback to name each area with confidence. Do not read every insight.

• For the largest themes in Deck's order, call explore_insights with theme_id and limit set to 50.
• Call explore_subthemes with theme_id and segment_scope: "all_customers" to see the finer topics in a theme. A subtheme that belongs to a different product area shows a theme to split. On the Free plan it returns feature_unavailable; use explore_insights instead.
• Call explore_insights with window_days set to 30 and limit set to 50 to read recent feedback that fits no theme well. Do not use since here: it returns every insight of the window and takes no limit.

5. Propose the target taxonomy

Map every current theme to one action: keep, rename, merge, split, new or archive. Show the user one table:

Naming rules:

• A name has 1 to 120 characters after Deck trims it.
• A name 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: call restore_theme instead of create_theme.
• Use plain product-area names that customers and the team use, for example "Search" or "Mobile app". Do not name a feeling ("Bad search") or a solution ("Add dark mode").
• Give each theme one product area. Prefer fewer, broader themes. Subthemes hold the detail inside a theme.
• Write a description of at most 1000 characters. Say what belongs and what does not. Deck's agents read the name and the description when they sort new feedback into themes.
• 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 this taxonomy?" Wait for a yes. Then list each merge and each archive, and get an explicit yes for each one.

6. Apply the taxonomy

Apply the rows in this order. Check each result before the next call.

1. Rename or describe: update_theme with theme_id and one or more of name, description and color. An empty description clears it.
2. New: create_theme with name, description and, when you know them, up to 100 insight_ids.
3. Merge: merge_themes with target_theme_id and 1 to 10 source_theme_ids. It moves every insight link to the target and archives the sources. It cannot be fully undone: restore_theme brings back an empty source theme. To give the target the name of a source, first rename the source with update_theme, then merge, then rename the target.
4. Split: create_theme for the new theme. 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_insights with theme_id, or from explore_subthemes with a subtheme_id and view set to insights.
5. Extra link: add_theme_insights when an insight also belongs to a second theme. An insight has at most 5 themes. Deck skips the others as at_theme_limit.
6. Archive: archive_theme only for a theme with no insights and no place in the taxonomy. restore_theme undoes it.

Read the lists in each result, such as added, moved, already_linked, not_linked and at_theme_limit, and report the skipped insights. 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.

7. Check the result

• Call explore_themes with each changed theme_id. Compare the name, description and insights with the approved table.
• Call explore_themes again for the full list. Show the final themes with Deck's counts and the deck_url of each changed theme.
• Tell the user that subthemes do not change now. Deck rebuilds them on the next synthesis run.

Deck still creates new themes when new feedback fits no theme. To keep the taxonomy clean, fetch and follow https://docs.getdeck.io/docs/agents/workflows/taxonomy-review.md from time to time.

Rules

• Build the taxonomy from this product and this feedback, not from a generic template.
• 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.
• MCP never deletes a theme or its insights. Theme tools act only on global themes. A survey theme returns NOT_FOUND.
• 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 row of the approved table is applied, or the user knows why it is not.
• explore_themes shows the approved names and descriptions, and no source theme of a merge is still active.
• The user knows that subthemes refresh on the next synthesis run.