/draft-plan

name: draft-plan
description: "Produce an implementation plan at .turbo/plans/[slug].md. Use when the user asks to \"draft a plan\", \"write an implementation plan\", \"plan this change\", or needs a first-draft plan file."

Draft Plan

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

Task Tracking

Use `TaskCreate` to create a task for each step:

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 `AskUserQuestion` 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. Neither does a constraint on the solution that the document carries from someone other than the user: it stays open for Step 4, however definitively the document states it.

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 via the Skill tool. 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 WebSearch 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 `AskUserQuestion` 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
• A constraint on the solution that someone other than the user set and the user has not confirmed, such as a request relayed from another session or a consuming project's stated needs, rules out an option that is sounder on technical merit; offer that option and name the constraint it relaxes

**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 thir