| name | writing-plans |
| description | Convert design docs into step-by-step TDD implementation plans. Use when the user says "write a plan", "implementation plan", "TDD plan", "break this into tasks", or has a design doc that needs to become executable steps. |
Writing Plans
Use this skill when the user has a completed design doc and needs a comprehensive implementation plan with exact file paths, complete code examples, and a TDD approach.
Purpose
Convert a validated design into a step-by-step implementation plan that any engineer can follow without prior codebase context. Each task is one action, 2-5 minutes of work.
Prerequisites
- A completed design document (from brainstorming or provided inline)
- The design doc path (e.g.,
docs/plans/YYYY-MM-DD-<topic>-design.md) or pasted content
Workflow
-
Read the design document.
If a path is provided, read the design doc. If no design is provided, ask the user to provide it before proceeding.
-
Write the plan header.
Every plan starts with: feature name, goal (one sentence), architecture (2-3 sentences), and tech stack.
-
Break work into phases.
Each phase covers one component. Within each phase, tasks follow strict TDD order:
- Write the failing test (complete code, not a placeholder)
- Run the test to confirm it fails (exact command + expected error)
- Write minimal implementation (complete code)
- Run the test to confirm it passes (exact command)
- Commit (exact git command)
-
Ensure bite-sized granularity.
Each step is one action, 2-5 minutes. Never write "add validation logic" as a single step. Break into: write test, run, implement, verify, commit.
-
Run adversarial review (R1-R6).
Before presenting the final plan, run these checks:
- R1 — Count integrity: numeric quantifiers match actual list items
- R2 — Acceptance criteria strength: no vague language, all measurable
- R3 — Scope violations: each task can actually deliver what it claims
- R4 — Integration traps: import paths, contract paths, API signatures verified
- R5 — Idempotency: resource creation has dedup keys and rerun behavior
- R6 — Verification soundness: each verification step graded strong/medium/weak
-
Save the plan and hand off.
Save to docs/plans/YYYY-MM-DD-<feature-name>.md. Output the handoff line referencing the path and pointing to plan-ticket.
Expected Output Format
A Markdown plan document with:
- Header (goal, architecture, tech stack)
- Phases with exact file paths (Create/Modify/Test)
- Complete code for each step (not pseudocode)
- Exact run commands with expected output
- Adversarial review summary (R1-R6)
- Handoff line with artifact path
Quality Checklist
