Writing Plans

1---
2name: writing-plans
3description: Use when you have a spec or requirements for a multi-step task, before touching code
4---
5 
6# Writing Plans
7 
8## Overview
9 
10Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
11 
12Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
13 
14**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
15 
16**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
17 
18**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
19 
20## Bite-Sized Task Granularity
21 
22**Each step is one action (2-5 minutes):**
23- "Write the failing test" - step
24- "Run it to make sure it fails" - step
25- "Implement the minimal code to make the test pass" - step
26- "Run the tests and make sure they pass" - step
27- "Commit" - step
28 
29## Plan Document Header
30 
31**Every plan MUST start with this header:**
32 
33```markdown
34# [Feature Name] Implementation Plan
35 
36> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
37 
38**Goal:** [One sentence describing what this builds]
39 
40**Architecture:** [2-3 sentences about approach]
41 
42**Tech Stack:** [Key technologies/libraries]
43 
44---
45```
46 
47## Task Structure
48 
49```markdown
50### Task N: [Component Name]
51 
52**Files:**
53- Create: `exact/path/to/file.py`
54- Modify: `exact/path/to/existing.py:123-145`
55- Test: `tests/exact/path/to/test.py`
56 
57**Step 1: Write the failing test**
58 
59```python
60def test_specific_behavior():
61    result = function(input)
62    assert result == expected
63```
64 
65**Step 2: Run test to verify it fails**
66 
67Run: `pytest tests/path/test.py::test_name -v`
68Expected: FAIL with "function not defined"
69 
70**Step 3: Write minimal implementation**
71 
72```python
73def function(input):
74    return expected
75```
76 
77**Step 4: Run test to verify it passes**
78 
79Run: `pytest tests/path/test.py::test_name -v`
80Expected: PASS
81 
82**Step 5: Commit**
83 
84```bash
85git add tests/path/test.py src/path/file.py
86git commit -m "feat: add specific feature"
87```
88```
89 
90## Remember
91- Exact file paths always
92- Complete code in plan (not "add validation")
93- Exact commands with expected output
94- Reference relevant skills with @ syntax
95- DRY, YAGNI, TDD, frequent commits
96 
97## Execution Handoff
98 
99After saving the plan, offer execution choice:
100 
101**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**
102 
103**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
104 
105**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
106 
107**Which approach?"**
108 
109**If Subagent-Driven chosen:**
110- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
111- Stay in this session
112- Fresh subagent per task + code review
113 
114**If Parallel Session chosen:**
115- Guide them to open new session in worktree
116- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans
117