--- title: "Plan an initiative" description: "Group related backlog opportunities into one Deck initiative with a goal, evidence and written sections." url: "/docs/agents/workflows/plan-initiative" --- This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth. # Plan an initiative — agent workflow * **Use it when:** the user says "group these opportunities", "plan an initiative for onboarding" or "what should our next big bet be?" * **Outcome:** one initiative has a title, a goal, 2 to 6 linked opportunities, evidence from each of them, an overview and an outcomes section. Projects that already exist for those opportunities sit under the initiative. * **Needs:** Deck MCP. Any member with MCP access can use the Build write tools. A segment focus needs segments to be on. ## 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](https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md). Stop this workflow until the tools work. ## 2. Find the candidates Make these calls at the same time: * `explore_opportunity_backlog` with `limit: 25`. Add `category` when the user names a type of problem. The list is in Deck's rank order. * `list_initiatives` with `query` set to the topic of the user. An initiative for the topic can exist already. If an initiative for the topic exists, show it and ask: "Add to this initiative, or create a new one?" Pick 2 to 6 opportunities that share one customer problem or one outcome. Open each one with `explore_opportunity_backlog` and its `opportunity_id`. Make these calls at the same time. Read `brief`, `evidence`, `segment_ids`, `linked_initiatives` and `linked_projects`. Leave out an opportunity when its evidence does not match the shared problem. Say why. ## 3. Draft the plan Show the user this draft: * **Title:** the shared outcome, for example "Faster first report for new admins". * **Goal:** one sentence with the change that the team wants. The user sets any target number. * **Anchor:** the opportunity with the best Deck rank. The initiative is created from it. * **Opportunities:** each one with Deck's impact score, evidence count and one reason to include it. * **Segments:** the segment IDs that most of the opportunities share, or none. * **Projects:** each Project in `linked_projects`. Warn that a move replaces the current parent initiative of that Project. Get a yes before step 4. ## 4. Create the initiative If the user picked an initiative that exists, use its `initiative_id` and go to step 5. Else call `create_initiative_from_opportunity` with the anchor `opportunity_id`, `title`, `goal` and `description`. Deck creates the initiative with its overview, evidence and outcomes sections and links it to the anchor. In a client that shows Deck views, you can call `create_from_insights` instead, with `action: "create_initiative"`, `title`, `goal` and `insight_ids`. This call saves nothing. The user must click **Create** in Deck's review. After the click, find the initiative with `list_initiatives` and `query` set to the title. Then link the anchor with `link_opportunity_initiative`. ## 5. Link the rest Make these calls at the same time: * `link_opportunity_initiative` with each other `opportunity_id` and the `initiative_id`. Other links of the opportunity stay. * `add_initiative_insights` with the `initiative_id` and up to 100 insight IDs from the evidence of the other opportunities. Use the `source_id` of each evidence row with `source_type: "INSIGHT"`. * `set_project_initiative` with each approved `project_id` and the `initiative_id`. * `set_initiative_segments` with the approved `segment_ids`, only when the draft has segments. It replaces the current segment set. ## 6. Write the sections Call `explore_build_initiatives` with the `initiative_id`. Read the current sections. `update_initiative_section` replaces the whole section, so keep what the user wrote before. Send `content_jsonb` in the format that `explore_build_initiatives` returns for sections. * `update_initiative_section` with `section_key: "overview"`: the shared problem in the customers' words, why it matters now, and the linked opportunities. * `update_initiative_section` with `section_key: "outcomes"`: the goal, and what must change in the feedback when the work ships. To change the goal later, use `update_initiative_goal`. ## 7. Set the status Call `update_initiative_status` with `status: "exploring"`, or the status that the user picks. Never set `archived` unless the user asks for it. ## 8. Confirm Make these calls at the same time: * `explore_build_initiatives` with the `initiative_id`. Report the title, the goal, the evidence, the Project status counts and the `deck_url`. * `explore_opportunity_backlog` with each linked `opportunity_id`. Check that `linked_initiatives` lists the initiative. For each opportunity that has no Project yet, offer the [Opportunity to delivery](/docs/agents/workflows/opportunity-to-delivery) workflow. ## Rules * Group by the customer problem, not by the team or the code area. * Keep 2 to 6 opportunities in one initiative. Propose a second initiative for more. * Use only IDs that Deck returned. Never invent IDs. * Quote Deck's numbers. Do not compute your own. Do not invent a target number for the goal. * Show the plan and get a yes before you call write tools. * Never ask for a `dk_` API key. ## Done when * `explore_build_initiatives` shows the initiative with a goal, evidence, an overview and an outcomes section. * Each approved opportunity lists the initiative in `linked_initiatives`. * Each approved Project sits under the initiative. See also: [Initiatives](/docs/features/initiatives), [Opportunity Backlog](/docs/features/opportunity-backlog) and [Segments](/docs/features/segments). --- [View full sitemap](/docs/sitemap)