Writing a Plan
Overview
Write a comprehensive implementation plan assuming the engineer knows nothing about our codebase and has poor taste. Document everything they need to know: which files, code, tests, documentation they might need to check for each task, and how to test. Break down the entire plan into small tasks. DRY. YAGNI. TDD.
Assume they are a skilled developer but know little about our toolset or problem domain. Assume they have limited knowledge of good test design.
Start with this statement: "I am using the writing-plans skill to create an implementation plan."
Save the plan to: docs/plans/YYYY-MM-DD-<feature-name>.md
Scope Check
If the specification covers multiple independent subsystems, it should be split into sub-project specifications during the brainstorming phase. If not, suggest splitting it into independent plans—one plan per subsystem. Each plan should independently produce runnable, testable software.
File Structure
Before defining tasks, plan which files will be created or modified, and what each file is responsible for. This is where decomposition decisions are made.
- Design units with clear boundaries and well-defined interfaces. Each file should have a single, clear responsibility.
- You reason best about code you can hold in your head at once; the more focused a file is, the more reliable your edits will be. Prefer small, focused files over large files that do too many things.
- Files that change together should be kept together. Split by responsibility, not by technical layer.
- In an existing codebase, follow established patterns. If the codebase uses large files, do not unilaterally restructure it—but if the file you're modifying has become unmanageable, it's reasonable to include splitting it in the plan.
This structure guides task decomposition. Each task should produce an independent, meaningful, self-contained change.
Task Granularity
Each step is an action (2-5 minutes):
- "Write a failing test" - Step
- "Run it to ensure it fails" - Step
- "Implement minimal code to make the test pass" - Step
- "Run the tests and ensure they pass" - Step
Plan Document Header
Every plan must start with this header:
markdown
# [Feature Name] Implementation Plan
**Goal:** [One-sentence description of what's being built]
**Architecture:** [2-3 sentences about the approach]
**Tech Stack:** [Key technologies/libraries]
---
Task Structure
markdown
### 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 a failing test**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
- [ ] **Step 2: Run the test to verify failure**
Run: `pytest tests/path/test.py::test_name -v`
Expected: Fails with "function not defined"
- [ ] **Step 3: Write the minimal implementation**
```python
def function(input):
return expected
```
- [ ] **Step 4: Run the test to verify pass**
Run: `pytest tests/path/test.py::test_name -v`
Expected: Passes
Remember
- Always use exact file paths
- Include full code in the plan (instead of "add validation")
- Exact commands and expected output
- Use @ syntax to reference related skills
- DRY, YAGNI, TDD
Plan Review Loop
After completing each chunk of the plan:
- Dispatch the plan document review sub-agent (see plan-document-reviewer-prompt.md) with carefully crafted review context—never your conversation history. This keeps the reviewer focused on the plan itself, not your thought process.
- Provide: Chunk content, specification document path
- If ❌ issues are found:
- Fix the issues in the chunk
- Re-dispatch the reviewer to review the chunk
- Repeat until ✅ approved
- If ✅ approved: Proceed to the next chunk (if it's the last chunk, move to execution handoff)
Chunk Boundaries: Use
headers to define chunks. Each chunk should be ≤1000 lines and logically self-contained.
Review Loop Guidelines:
- The same agent that wrote the plan fixes it (retains context)
- If the loop exceeds 5 iterations, seek guidance from a human
- The reviewer is an advisor—if you disagree with feedback, explain your reasoning
Execution Handoff
After saving the plan:
"Plan completed and saved to . Ready for execution?"