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

Sort uncategorized insights — agent workflow

• Use it when: the user asks "which insights are not grouped yet?", "clean up the uncategorized insights" or "sort the new feedback into subthemes", or after a large import.
• Outcome: each uncategorized insight of the chosen themes is in a subtheme that fits, in a better theme, or left for the next synthesis run with a reason.
• Needs: Deck MCP and the Starter plan or higher, because subthemes need it. Every member with MCP access can use the subtheme write tools. They spend no credits.

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. Find the themes with uncategorized insights

Ask the user which themes to sort. When the user does not say, take the top themes of explore_themes in Deck's order.

Call explore_subthemes with each theme_id and segment_scope: "all_customers". Make these calls at the same time. Do not set segment_ids. Without segment_scope: "all_customers", an organization with segments gets the subthemes of every segment, but theme_summary always counts all customers. With it, the subtheme list, the uncategorized list, the writes and theme_summary all use the same all-customer subthemes.

• feature_unavailable: the plan does not include subthemes. Tell the user that subthemes need the Starter plan or higher. Stop.
• theme_summary.uncategorized_insight_count is the number of the theme's insights that are not in a subtheme yet. Quote it.
• theme_summary.below_threshold is true when the theme needs 5 or more insights before Deck builds subthemes. Skip that theme: it has no subthemes to place insights into.

Start with the themes that have the most uncategorized insights.

3. Read the uncategorized insights and the subthemes

• Take any subtheme_id from the theme's list. Call explore_subthemes with that subtheme_id and view set to uncategorized. It returns up to 100 of the theme's uncategorized insights with quotes for each call. Page with offset.
• Read the name and insight count of each subtheme in the list. When a name is not clear, call explore_subthemes with its subtheme_id to read its narrative and key quotes.

4. Decide where each insight goes

Give each insight one of these outcomes:

• Fits a subtheme of this theme: add it to that subtheme.
• Belongs to another theme: move it to that theme. Find the theme with explore_themes and a query word.
• Fits nothing well: leave it. When several insights share a new topic, the next synthesis run can build a subtheme from them.

Do not force a fit. A wrong placement is worse than an uncategorized insight.

Show the user a table: insight name, short quote, outcome, target subtheme or theme. Group the rows by target. Ask: "Apply this plan?" Wait for a yes.

5. Apply the plan

• Add to a subtheme: add_subtheme_insights with subtheme_id and up to 100 insight_ids. Read added and not_uncategorized. An insight in not_uncategorized is no longer in the uncategorized list, for example because a teammate or a synthesis run placed it. Skip it.
• Move to another theme: move_theme_insights with source_theme_id, target_theme_id and up to 100 insight_ids. Read moved and not_linked. The insight shows in the subthemes of the target theme after the next synthesis run.
• Fix a wrong subtheme: move_subtheme_insights with source_subtheme_id, target_subtheme_id and up to 100 insight_ids. Both subthemes must be in the same theme and the same segment scope. Otherwise Deck returns VALIDATION_ERROR.

Send the subtheme writes (add_subtheme_insights, move_subtheme_insights and delete_subtheme) for one theme one at a time. Wait for the result of each write before you send the next one. When a subtheme write returns CONFLICT, another write changed the subthemes of that theme at the same time. Call explore_subthemes with the theme_id and segment_scope: "all_customers" again, make sure that the plan still fits, and then send the write again.

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_subthemes with the same theme_id and segment_scope: "all_customers" again. Quote the new theme_summary.uncategorized_insight_count.
• Call explore_subthemes with each target subtheme_id and view set to insights to show the insights it holds now.
• Tell the user that Deck rebuilds subthemes on the next synthesis run. That run can change the groups.

Rules

• Quote Deck's numbers. Do not compute your own.
• Show the plan and get a yes before you call write tools.
• Do not call delete_subtheme in this workflow unless the user asks. It is a sensitive write: it removes the subtheme and puts its insights back in the uncategorized list. Get an explicit yes every time.
• Moving an insight to another theme changes the theme taxonomy. When many insights belong elsewhere, fetch and follow https://docs.getdeck.io/docs/agents/workflows/taxonomy-review.md.
• 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 uncategorized insight of the chosen themes has an outcome that the user approved.
• Each approved write returned success, and explore_subthemes shows the new uncategorized count.
• The user knows which insights wait for the next synthesis run.