writing-plans

Writing Plans

Create an implementation plan another agent can execute with minimal ambiguity.

Output Path

Save to docs/plans/YYYY-MM-DD-<feature-name>.md.

Plan Header

# <Feature Name> Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use the appropriate execution skill (`executing-plans` or `subagent-driven-development`) to implement this plan.

**Goal:** <single sentence>
**Architecture:** <2-4 sentences>
**Tech Stack:** <languages/libraries/tools>
**Assumptions:** <list the key assumptions this plan rests on. For each, state what it excludes: "Assumes X — will NOT work if Y."> *(skip only if the plan contains zero conditional logic)*

---

Task Rules

• Keep tasks independent when possible.
• Keep each step to one action (roughly 2-5 minutes).
• Use exact file paths.
• Include exact verification commands and expected outcomes.
• Use TDD ordering when code behavior changes.
• For ambiguous features, ask clarifying questions before finalizing the plan rather than guessing.

Task Template

### Task N: <Name>

**Files:**
- Create: `<path>`
- Modify: `<path>`
- Test: `<path>`

**Does NOT cover:** *(required when this task adds a condition, gate, trigger, or any "when X do Y" logic — state the scenarios the condition excludes. If an excluded scenario should be covered, revise this task before implementing.)*

**Step 1: Add failing test**
Run: `<command>`
Expected: fail for the intended reason

**Step 2: Implement minimal change**
Describe exact edits (include code only where non-obvious).

**Step 3: Verify task**
Run: `<command>`
Expected: pass

**Step 4: Commit**
```bash
git add <files>
git commit -m "<message>"
```

Quality Bar

• No vague steps like "update logic".
• No hidden dependencies between distant tasks.
• Call out migrations, feature flags, and rollback checks when relevant.
• Prefer small vertical slices over large horizontal phases.

Plan Review

After saving the plan, dispatch a plan-reviewer subagent using the prompt template in plan-document-reviewer-prompt.md. Replace [PLAN_FILE_PATH] with the saved plan path and [SPEC_FILE_PATH] with the approved design document path. The reviewer cross-checks the plan against the spec — not just the plan in isolation.

The reviewer checks for:

• Vague or ambiguous steps
• Missing file paths or verification commands
• Hidden dependencies between tasks
• Incorrect TDD ordering
• Scope gaps or drift compared to the approved design

If the reviewer returns Issues Found, revise the plan before offering execution options.

Handoff

After review passes, present exactly two options:

1. Recommended: subagent-driven-development in this session — parallel execution with per-task review gates (best quality)
2. Alternative: executing-plans in a separate session — sequential batch execution (simpler, works in any session)