--- title: "Build from evidence" description: "Implement a Deck Project in the codebase, with each change traced to the customer insights in the Project's evidence." url: "/docs/agents/workflows/build-from-evidence" --- This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth. # Build from evidence — agent workflow * **Use it when:** the user says "build this Project", "implement what customers asked for in this Project" or "fix the issues in this Deck Project". * **Outcome:** the code change does what the Project asks. Each requirement cites the Deck insights behind it. Tests pass. The Deck Project shows `in_progress`. * **Needs:** Deck MCP and write access to the codebase. To read a linked Linear or Jira item, the client needs its own Linear or Jira tools. Deck stores only the link. ## 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. Open the Project * The user pasted a Deck link: call `get_platform_links` with `urls`. Use the `project_id` from the result. * The user named the Project: call `list_projects` with `query`. * The user named nothing: call `explore_workspace` with `view: "members"` to get the user's own `user_id`. Then call `list_projects` with `owner_user_id` and `status: "not_started"`. Ask the user to pick one. Call `explore_build_projects` with the `project_id`. Read the overview, the success metrics, `evidence.active_references`, `external_links` and the parent initiative. If the Project has no evidence, stop. Offer to find evidence with `explore_insights` and `query`, or with `explore_subthemes` and `view: "insights"`. Add it with `add_project_insights` after a yes. ## 3. Read the evidence Call `explore_insights` with each `insight_id` from `evidence.active_references`, at the same time. Read at most 20 first. Read the name, the category, the sentiment, the quotes and the source. * For a bug, call `read_transcript` with the `feedback_id` of the insight. Look for the steps, the screen and the error text. * When `external_links` has a Linear or Jira item, read it with the client's own Linear or Jira tool. Deck tools do not read the item body. ## 4. Write the requirements Group the insights by the problem they describe. For each group, write: * **Requirement:** one sentence that a test can check. * **Evidence:** the insight IDs and the number of insights in the group. * **Type:** a bug (`BUGS_AND_ERRORS`), a usability issue (`USABILITY_ISSUES`) or a feature request (`FEATURE_REQUESTS`). List the requests that you leave out, with the reason. When customers ask for opposite things, write both and ask the user to choose. ## 5. Map the requirements to the code Search the codebase for the screens, the routes and the error text in the quotes. For each requirement, name the files to change and the test to add. For a bug, write a failing test that shows the bug before you fix it. ## 6. Show the plan Show the user the requirements, the files, the tests and the Deck updates in steps 7 and 8. Get a yes before you change code or call write tools. ## 7. Build Call `update_project_status` with `project_id` and `status: "in_progress"` before you change code. Do not set `completed`. The team sets it when the change ships. Follow the rules of the repository, for example its AGENTS.md or CLAUDE.md file. Keep the change inside the approved requirements. If you find more work, ask before you add it. Run the tests and the type check of the repository. ## 8. Collect feedback on the change (optional) Call `create_feedback_widget` with `name` and `project_id`. Then call `explore_widgets` with the `widget_id` and follow its `install_prompt` to install the SDK on the new surface. New feedback then shows on the Project's Feedback tab. The prompt reads the publishable key from an environment variable. Never put a key in the code. See [SDKs](/docs/sdks). ## 9. Write the pull request In the pull request description, add: * The `deck_url` of the Project. * Each requirement with the Deck links of its insights. Each `explore_insights` result from step 3 has a `deck_url`. * The tests that you added. ## Rules * Build only what the evidence and the Project sections support. * Each requirement cites at least one insight ID from Deck. Never invent IDs. * Never copy customer names, emails or quotes with personal data into code, test data, commits or pull requests. Link to the insight in Deck. * Quote Deck's numbers. Do not compute your own. * Show the plan and get a yes before you call write tools. * Deck tools do not change Linear or Jira. * Never ask for a `dk_` API key. ## Done when * Each approved requirement has code and a test, and the tests pass. * The pull request links the Deck Project and the insights. * `explore_build_projects` shows the Project as `in_progress`. * After the release, offer the [Release impact check](/docs/agents/workflows/release-impact-check) and [Customer follow-up](/docs/agents/workflows/customer-follow-up) workflows. See also: [Projects](/docs/features/projects), [Insights](/docs/data-points/insights) and [Model Context Protocol](/docs/integrations/mcp). --- [View full sitemap](/docs/sitemap)