Writing Plans
Overview
Write 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.
Assume 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.
Announce at start:
"I'm using the writing-plans skill to create the implementation plan."
Context:
This should be run in a dedicated worktree (created by brainstorming skill).
Save plans to:
docs/superpowers/plans/YYYY-MM-DD-
[Feature Name] Implementation Plan
** For agentic workers: ** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (
- [ ]) syntax for tracking. ** Goal: ** [One sentence describing what this builds] ** Architecture: ** [2-3 sentences about approach] ** Tech Stack: ** [Key technologies/libraries]
Task Structure
Task N: [Component Name]
**
Files:
**
-
Create:
exact/path/to/file.py
-
Modify:
exact/path/to/existing.py:123-145
-
Test:
tests/exact/path/to/test.py
-
[ ]
**
Step 1: Write the failing test
**
python
def
test_specific_behavior
(
)
:
result
=
function
(
input
)
assert
result
==
expected
-
[ ]
**
Step 2: Run test to verify it fails
**
Run:
pytest tests/path/test.py::test_name -v
Expected: FAIL with "function not defined"
-
[ ]
**
Step 3: Write minimal implementation
**
python
def
function
(
input
)
:
return
expected
-
[ ]
**
Step 4: Run test to verify it passes
**
Run:
pytest tests/path/test.py::test_name -v
Expected: PASS
-
[ ]
**
Step 5: Commit
**
bash
git
add
tests/path/test.py src/path/file.py
git
commit
-m
"feat: add specific feature"
Remember Exact file paths always Complete code in plan (not "add validation") Exact commands with expected output Reference relevant skills with @ syntax DRY, YAGNI, TDD, frequent commits Plan Review Loop After completing each chunk of the plan: Dispatch plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process. Provide: chunk content, path to spec document If ❌ Issues Found: Fix the issues in the chunk Re-dispatch reviewer for that chunk Repeat until ✅ Approved If ✅ Approved: proceed to next chunk (or execution handoff if last chunk) Chunk boundaries: Use
Chunk N:
headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained.
Review loop guidance:
Same agent that wrote the plan fixes it (preserves context)
If loop exceeds 5 iterations, surface to human for guidance
Reviewers are advisory - explain disagreements if you believe feedback is incorrect
Execution Handoff
After saving the plan:
"Plan complete and saved to
docs/superpowers/plans/