Writing plans

Writing Implementation Plans

Purpose

Create comprehensive plans assuming the implementer has zero context.

"I'm using the Writing Plans skill to create the implementation plan."

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

Plan Header Template

# [Feature Name] Implementation Plan

**Goal:** [One sentence]
**Architecture:** [2-3 sentences]
**Tech Stack:** [Key technologies]
**Estimated Tasks:** [count]

---

Task Granularity

Each step = ONE action (2-5 minutes):

• "Write the failing test" ← step
• "Run it to confirm failure" ← step
• "Implement minimal code" ← step
• "Run tests, confirm pass" ← step
• "Commit" ← step

NOT: "Write tests and implement feature" ← too big

Task Structure

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.ts:lines`
- Test: `tests/path/to/test.ts`

**Step 1: Write failing test**
\`\`\`typescript
test('should do X', () => {
  expect(thing()).toBe(expected);
});
\`\`\`

**Step 2: Verify failure**
Run: `npm test -- --grep "should do X"`
Expected: FAIL - "thing is not defined"

**Step 3: Implement**
\`\`\`typescript
export function thing() {
  return expected;
}
\`\`\`

**Step 4: Verify pass**
Run: `npm test -- --grep "should do X"`
Expected: PASS

**Step 5: Commit**
\`\`\`bash
git add -A && git commit -m "feat: add thing"
\`\`\`

Plan Principles

Principle	Meaning
DRY	Don't repeat yourself
YAGNI	Don't build what's not needed
TDD	Test first, always
Small commits	One logical change per commit

What to Include

• ✅ Exact file paths
• ✅ Complete code snippets (not "add validation")
• ✅ Exact commands with expected output
• ✅ Dependencies to install
• ✅ Environment setup needed

Handoff

After saving plan:

**Plan saved to `docs/plans/[filename].md`**

Ready to execute. Options:
1. **Execute now** - I'll work through tasks with you
2. **Subagent execution** - Fresh agent per task with review gates
3. **Later** - Plan saved for future session

If executing → Use executing-plans skill