Draft Plan

Draft Plan

Produce an implementation plan at .turbo/plans/<slug>.md. Capture the task, survey patterns, escalate decisions, discuss, and draft.

Task Tracking

Use update_plan to track each step, restating any remaining steps of a parent workflow alongside them:

1. Capture the task and pick a slug
2. Run $survey-patterns skill
3. Consult task-specific skills and docs
4. Escalate product decisions
5. Deep-dive discussion
6. Draft and write the plan file
7. Present summary
8. Act on the user's reply

Step 1: Capture the Task and Pick a Slug

Absorb the user's request without interrupting. Restate the goal in one or two sentences and confirm.

Generate a slug for the plan file from the task title:

• Lowercase
• Replace non-alphanumeric characters with hyphens
• Collapse consecutive hyphens
• Trim leading and trailing hyphens
• Truncate to 40 characters at a word boundary

Example: "Add a caching layer to the image pipeline" → add-a-caching-layer-to-the-image-pipeline.

If .turbo/plans/<slug>.md already exists, append -2, -3, etc. until the path is free. Do not overwrite.

The user may pass an explicit slug or output path in their request (e.g., "draft plan as auth-rewrite"). If so, honor it. If .turbo/plans/<slug>.md exists in that case, use request_user_input to ask whether to overwrite, append a numeric suffix, or pick a different slug.

A path to a file that already exists is background input rather than an output destination. Treat it as the output path only when the request says so explicitly.

State the chosen slug and the resulting plan path before continuing.

Background Document as Input

If a path to a background document is passed as input (a design doc, an issue, a written proposal), treat it as the source of truth for product decisions and discussion areas. Read it, then:

• In Step 4, skip escalation for any product decision the document resolves. Only escalate questions it did not answer.
• In Step 5, skip deep-dive areas the document covers. Only discuss areas it did not address.
• Confirm the deployment's bounds with the user even when the document states them, rather than carrying them over as settled.

A question is resolved only when the document makes a definitive statement that answers it. Mentions without a chosen direction, open questions, and deferred decisions do not count as resolved; escalate those normally.

Step 2 (pattern survey) and Step 3 (consult skills and docs) still run in full. The document describes what; $draft-plan still surveys how.

Step 2: Run $survey-patterns Skill

Run the $survey-patterns skill with the confirmed task description. Keep the returned findings in conversation context for use in Steps 5 and 6.

Step 3: Consult Task-Specific Skills and Docs

Ground library and framework choices in current reality before escalating decisions.

1. Scan for matching skills. Compare the task description against available skill trigger descriptions. For each unambiguous match, run the skill by reading and following the installed skill instructions. This loads decision-level guidance (idiomatic patterns, known pitfalls, version constraints) before product decisions are made. If unsure, do not load.
2. Look up library docs. For libraries or frameworks the task clearly depends on, query documentation MCP tools (or web search as a fallback) when the decision hinges on current library state such as whether a feature exists, which versions support it, or whether an API has been deprecated.
3. Read both sides of an interface the task implements or adapts. Read the interface's shipped declaration at the installed version in full, including the obligations its documentation places on implementers; it outranks hosted docs for version-exact facts. Read the production code on the other side as well: the implementation real callers pass in, or the caller that drives the new work.

Keep findings at the decision level: what a library can do, which approach is idiomatic, which version to target. Do not embed specific API signatures or code snippets into the plan. Those belong at execution time, where the same skills are re-loaded.

Step 4: Escalate Product Decisions

Identify product or design decisions the user's request did not resolve. Escalate these via request_user_input before drafting steps.

Escalate when:

• A plan step requires choosing between user-facing behaviors the request did not specify (opt-in vs opt-out, strict vs lenient, sync vs async)
• The plan assumes product requirements that were not stated
• Design trade-offs affect UX or product direction rather than technical implementation
• Multiple valid approaches exist and the choice is a matter of product preference, not technical merit
• The plan would introduce a pattern not yet established in this codebase, or follow one sourced from outside it
• The plan adds consistency or durability machinery (a lease, lock, queue, versioning scheme, or new persistent entity) that no stated requirement or deployment bound demands; carrying that machinery is itself a product decision

Do not escalate technical decisions the agent can make autonomously: which data structure, which existing pattern to follow, internal implementation approach. The boundary is product intent.

Confirm external constraints before escalating. When an option depends on a third-party API, service, or platform behaving a particular way, drop it unless that behavior is confirmed by current documentation.

Look up a named precedent before escalating. When the request or a background document names a precedent the design is meant to follow, such as an existing product, a protocol, or a standard, look up how it behaves on the points the design touches, and frame options against what the lookup found. Mark as unverified only a claim about it that the lookup could not settle.

Observe existing surfaces before escalating. When an option concerns how an existing surface looks, observe it as it currently renders, by running the app from the current code, or from a screenshot requested from the user, and drop any option its rendered state rules out.

Apply the UX lens before escalating. When a decision concerns what the software does for the person using it, a default or a control included, run the $user-experience skill on it first, and state each option as the behavior that person gets and the goal it serves. Leave the mechanism behind each behavior to the plan.

Output what is at stake as text first, even when the reading it came from is fresh in this conversation. When the decision turns on a failure or misuse scenario, that means the invariant the change would protect and what makes that scenario reachable given the existing guards. Then use request_user_input to present the decision as a concise trade-off with options. Mark the strongest option "(Recommended)" and place it first. Treat the work of departing from the codebase's existing structure as a cost to state beside the option that incurs it, with no bearing on which option is strongest. Draft plan steps that depend on these decisions only after the user responds.

Offer a Get a second opinion option whenever the decision is costly to reverse (it establishes a pattern others will follow, defines an interface, commits to a data shape, or imports a pattern the codebase has not used), and whenever no option earns "(Recommended)" with conviction. It runs the $consult-claude skill for what each option commits to, what reversing it costs, and what the prevailing convention is. Hold the concrete options to two so the question stays within the three-option limit. Then resolve the decision with that answer in hand, re-asking when the choice stays the user's.

Step 5: Deep-Dive Discussion

Interview the user relentlessly about every aspect of the implementation shape until you reach shared understanding. Use request_user_input, one question at a time. Use the pattern survey findings to frame choices. Cover whichever of these matter for the task. Do not present a rigid checklist.

Settle the first two rows before the rest, so implementation choices land against concrete outcomes and bounds instead of being taken in the abstract. When the user jumps to implementation shape early, engage briefly then circle back.

Discussion Guidelines

• If a question can be answered by exploring the codebase, explore the codebase instead.
• When a question concerns how an existing surface looks, observe it as it currently renders, by running the app from the current code, or from a screenshot requested from the user, before framing options. Drop any option its rendered state rules out.
• When a question concerns how to guard against a state, find where that state is constructed before framing options. When a single place constructs it, offer making the state impossible to construct there alongside the shapes that detect it downstream or change its consumers.
• When a question defines a boundary, contract, or data shape, add a Get a second opinion option and hold the concrete options to two so the question stays within the three-option limit. It runs the $consult-claude skill for the soundest answer on technical merit alone, independent of the task's original scope; on a question of product intent, run it for what each answer commits to and what reversing it costs. Then resolve the question with that answer in hand, re-asking when the choice stays the user's.
• When a question turns on how a surface looks or how an interaction behaves, and an answer in prose would leave the user guessing, add a Prototype it first option and hold the concrete options to two so the question stays within the three-option limit. It runs the $prototype skill on that unknown, then asks the question again with the prototype in hand. A confirmation of outcomes is such a question when the outcomes describe what a control or gesture does in use.
• When a question concerns what the software does for the person using it, a default or a control included, run the $user-experience skill on it before framing options, and state each option as the behavior that person gets and the goal it serves.
• Pair each question with a recommendation and the reasoning behind it, so the discussion stays collaborative.
• Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
• When the user says "you decide," make the call and explain why.
• Probe short answers before moving on.
• Before closing the discussion, hold each decision resolved in Step 4 or earlier in this step against the shape as it now stands: re-read what its chosen option was described as doing. Where a description no longer holds, name the claim that fails and re-ask that decision.
• When the shape is clear or the user signals readiness, confirm before drafting.