# Plan Draft > Planning rules and plan template for drafting implementation plans. Invoked as /plan-draft for an ad-hoc planning session, or used by the planner sub-agent in the /feature workflow. (Named plan-draft so it does not collide with Claude Code's built-in plan-mode /plan command.) - Skill: `cunhaax/plan-draft` (Agent Skill) - Install (CLI): `npx skillmds@latest add cunhaax/plan-draft` - Raw SKILL.md: https://api.skillmd.com/api/skills/cunhaax/plan-draft/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: cunhaax (https://skillmd.com/u/cunhaax) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cunhaax/plan-draft --- # /plan-draft — Implementation Planning Use this skill to produce a structured implementation plan before writing any code. Can be invoked standalone (`/plan-draft`) or applied by the `planner` sub-agent during the `/feature` workflow. --- ## Context Gathering Before planning, collect all relevant context: - **External specs**: If the prompt references an external link or doc, fetch it before planning — the Requirements section must quote the source verbatim. - **Codebase**: Read any module-specific `AGENTS.md` files in directories likely to be affected, ADRs in `docs/adr/`, and relevant product docs in `docs/`. --- ## Planning Rules - **The Approval Summary is what the developer approves.** It is read on a phone, so constrain the units, not the total: goal in 1–2 sentences, one line per acceptance criterion, one line per key decision, one line per NEEDS_DECISION. There is no hard line cap — the per-item limits keep it short. If the acceptance criteria grow past ~10, treat that as a signal the task should be split into smaller slices, not that the summary should be longer. Each acceptance criterion must be user-visible behaviour, not implementation ("a visitor submitting an invalid form sees the error next to the field", not "add a guard clause in the controller"). Number each criterion `AC--n`, where `` is derived from the current git branch name: strip one leading type prefix if present (`worktree-`, `feat-`, `feature-`, `fix-`, `bugfix-`, `hotfix-`, `chore-`, or similar — these are redundant, every branch in the suite has one), replace remaining `/` with `-`, and truncate to 30 characters — plain `AC-n` restarts at 1 for every feature and collides with every other feature's `AC-1` once tests live side by side in the same suite, so the slug is what keeps the tag globally unique, greppable, and short. Every `AC--n` MUST map to at least one Test Strategy entry tagged `[AC--n]`; a criterion with no test is an incomplete plan. Everything below the summary is the detailed contract the summary stands on — the two must never disagree. - **The Contract section is written before Approach** and is what the end-to-end tests are coded against. For full-stack slices it pins routes, fields/params, response shapes, error rendering, and schema changes. Deviating from an approved Contract during implementation is a material change requiring re-approval. Mark it "None" for pure backend/infra work. - **Lead with intent.** The **Context & Decisions** section states, in a few sentences, what problem this solves and the shape of the solution — then lists every decision taken during planning and every alternative considered and rejected, each with its reason. The plan is self-contained: a reader with no access to the planning conversation must understand what to build and why. Nothing load-bearing may live only in the chat. - The **Requirements** section MUST capture the complete feature requirements exactly as specified by the user or the linked spec. Do not summarize or omit details — the `code-critic` cross-checks every requirement and edge case in this section against the committed tests. If they come from a document, quote them; if from the user's prompt, reproduce them in full. - The **Files** section MUST list every file the change touches, each tagged `NEW` / `EDIT` / `DELETE` / `MOVE`, with a phrase on what changes and why. It is the implementer's checklist and the reviewer's blast-radius map — a file in the diff but not here is an undiscussed change. - The **Out of Scope** section MUST state the boundary explicitly: what a reader might reasonably expect this change to include but it deliberately does not. This is where scope disagreements surface cheaply and what stops the implementer gold-plating. Write "None" only if you mean it. - List ALL edge cases explicitly in **Edge Cases** — do not assume any can be skipped. Number each edge case `EDGE--n`, reusing the same `` derived for acceptance criteria (see above) — plain `edge-N` restarts at 1 for every feature and collides with every other feature's `edge-1` once tests live side by side in the same suite. Every `EDGE--n` MUST map to at least one Test Strategy entry tagged `[EDGE--n]`; an edge case with no test is an incomplete plan. - Flag any potential single-responsibility concerns in the proposed approach. - Propose a test strategy that covers the happy path AND every identified edge case. Tests are the plan's deterministic oracle — every claim the plan makes about user-visible behaviour (error placement, section open/closed state, button enable/disable, post-failure page coherence, persistence-vs-UI consistency) MUST map to a committed end-to-end test that exercises the behaviour and observes the rendered result (per project convention; e.g., Playwright for a web UI). If a UI claim is worth writing down in the plan, it is worth committing as a test. - Do NOT write a manual "Verification" or "QA checklist" of behavioural steps. If you catch yourself writing "Try X and confirm Y", convert it into a committed test assertion in the Test Strategy. The one exception is **environmental preconditions** that are not themselves behaviour under test (e.g. "a migration was edited in place, so the local DB must be reset first") — record those under **Environment & Preconditions**, not as verification. - Prefer concrete, quotable statements over prose blobs: name the files, show the key data class or signature, number the edge cases. The plan is reviewed line by line — a reviewer can only annotate what is stated specifically. Where an existing pattern should be followed, point at it by name (e.g. "mirror `ExistingValidator`") so the implementer copies the canonical shape. - If any part of the spec is ambiguous, flag it as `NEEDS_DECISION` with options. Do NOT ask the user directly from within a sub-agent — surface ambiguities in the plan so the main agent can relay them. - Respect existing ADRs. If your plan contradicts a past decision, flag it explicitly and explain why the decision should be reconsidered. - Sections that genuinely do not apply may be marked "None" (Out of Scope, Environment & Preconditions, NEEDS_DECISION) — but do not drop them; "None" tells the reader you considered them. --- ## Plan Template ```markdown # Implementation Plan: [Feature Name] ## Approval Summary **Goal:** [1–2 sentences — what the user gains] **Acceptance Criteria** — each user-visible and testable (`` = current git branch name with a redundant leading type prefix like `feat-`/`fix-`/ `worktree-` stripped, `/` replaced by `-`, truncated to 30 chars): - AC--1: [one line: given/when/then] - AC--2: [...] **Key decisions:** [2–3 bullets, one line each] **Risk flags:** security surface: [yes/no] · new persisted field: [yes/no] · sensitive-category data: [yes/no] · schema migration: [yes/no] · new dependency: [yes/no] · new/changed route: [yes/no] **NEEDS_DECISION:** [one line each, or "None"] *(The summary above is what the developer approves; everything below is the detailed contract it stands on.)* ## Source [User prompt summary / external doc title + URL] ## Context & Decisions [Why this change exists and the shape of the solution, in a few sentences. Then: decisions taken during planning, and alternatives considered and rejected — each with its reason.] ## Requirements [Complete feature requirements — quoted from the source or reproduced verbatim from the prompt. Do not summarize.] ## Contract _(full-stack slices; "None" for pure backend/infra work)_ - Routes: [METHOD /path — purpose, required authority] - Form fields / params: [name, type, validation rule] - Response shape: [full page / fragment + target / redirect (per the project's redirect convention, if any)] - Error rendering: [where errors surface, message keys] - Schema: [tables/columns added or changed] ## Approach [Step-by-step implementation strategy. Point at existing patterns to follow by name where one applies.] ## Files - NEW [path]: [what it holds / why] - EDIT [path]: [what changes / why] - DELETE [path]: [why] - MOVE [old] → [new]: [why] ## Out of Scope - [What a reader might expect but this change deliberately excludes] ## Edge Cases _(`` = same slug as Acceptance Criteria above)_ - EDGE--1: [Edge case]: [handling strategy] - EDGE--2: [...] ## Test Strategy - [AC--1] [test name]: [what it verifies] - [AC--2] [...] - [EDGE--1] [test name]: [what it verifies] ## Environment & Preconditions [Non-behavioural setup the implementer needs — e.g. "migration edited in place, reset the local DB first". Behavioural claims belong in Test Strategy. "None" if nothing applies.] ## NEEDS_DECISION - [Ambiguity]: [options available] ## Risks - [Anything that could go wrong or needs extra attention] ``` --- ## Output Return the plan as markdown text. Do NOT write any files — the main agent will submit the plan for review. Do NOT write implementation code. Output only the plan.