Planning
Core Principle
Context window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
Planning tokens are cheaper than implementation tokens. Front-load thinking; scale effort to complexity.
When to Plan
- Always plan: multi-file changes, new features, refactors, >5 tool calls
- Skip planning: single-file edits, quick lookups, simple questions
Planning Files
Create in project root before starting work:
| File |
Purpose |
Update When |
task_plan.md |
Phases, tasks, decisions, errors |
After each phase |
findings.md |
Research, discoveries, code analysis |
After any discovery |
progress.md |
Session log, test results, files changed |
Throughout session |
Plan Template
# Plan: [Feature/Task Name]
## Approach
[1-3 sentences: what and why]
## Scope
- **In**: [what's included]
- **Out**: [what's explicitly excluded]
## Phase 1: [Name]
**Files**: [specific files, max 5-8 per phase]
**Tasks**:
- [ ] [Verb-first atomic task] — `path/to/file.ts`
- [ ] [Next task]
**Verify**: [specific test: "POST /api/users → 201", not "test feature"]
**Exit**: [clear done definition]
## Phase 2: [Name]
...
## Open Questions
- [Max 3, only truly blocking unknowns]
Phase Sizing Rules
Every phase must be context-safe:
- Max 5-8 files touched
- Max 2 dependencies on other phases
- Fits in one 2-4 hour session (implementation + verification + fixes)
- If a phase violates these → split it
Clarifying Questions
Scale to complexity:
- Small task: 0-1 questions, assume reasonable defaults
- Medium feature: 1-2 questions on critical unknowns
- Large project: 3-5 questions (auth, data model, integrations, scope)
Only ask if truly blocking. Make reasonable assumptions for everything else.
Task Rules
- Atomic: one logical unit of work per task
- Verb-first: "Add...", "Create...", "Refactor...", "Verify..."
- Concrete: name specific files, endpoints, components
- Ordered: respect dependencies, sequential when needed
- Verifiable: include at least one validation task per phase
Context Management Rules
| Situation |
Action |
| Starting new phase |
Read task_plan.md (refresh goals in attention window) |
| After any discovery |
Write to findings.md immediately |
| After completing phase |
Update task_plan.md status, log to progress.md |
| After viewing image/PDF |
Write findings NOW (multimodal content doesn't persist) |
| Resuming after gap |
Read all planning files |
| Just wrote a file |
Don't re-read it (still in context) |
| Error occurred |
Log to task_plan.md, read relevant files for state |
Error Protocol
ATTEMPT 1: Diagnose root cause → targeted fix
ATTEMPT 2: Different approach (different tool, library, method)
ATTEMPT 3: Question assumptions → search for solutions → update plan
AFTER 3 FAILURES: Escalate to user with what you tried
Never repeat the exact same failing action. Track attempts, mutate approach.
Iterative Refinement
For complex projects, iterate on the plan before implementing:
- Draft initial plan
- Review for gaps, missing edge cases, architectural issues
- Revise until suggestions become incremental
- Only then start implementation
5-Question Context Check
If you can answer these, your planning is solid:
| Question |
Source |
| Where am I? |
Current phase in task_plan.md |
| Where am I going? |
Remaining phases |
| What's the goal? |
Approach section |
| What have I learned? |
findings.md |
| What have I done? |
progress.md |
Anti-Patterns
| Don't |
Do Instead |
| Start coding without a plan |
Create task_plan.md first |
| State goals once and forget |
Re-read plan before decisions |
| Hide errors and retry silently |
Log errors, mutate approach |
| Keep everything in context |
Write large content to files |
| Repeat failed actions |
Track attempts in plan file |
| Create vague tasks ("improve X") |
Concrete verb-first tasks with file paths |
| Plan phases with 12+ files |
Split into 5-8 file chunks |
| Plan at 100% capacity |
Budget for verification, fixes, and unknowns |
1---2name: planning-23description: Software implementation planning with file-based persistence (task_plan.md, findings.md, progress.md). Use when asked to "plan", "break down this feature", "implementation plan", or starting complex tasks needing >5 tool calls. Apply proactively before non-trivial coding.4---56# Planning78## Core Principle910```11Context window = RAM (volatile, limited)12Filesystem = Disk (persistent, unlimited)13→ Anything important gets written to disk.14```1516Planning tokens are cheaper than implementation tokens. Front-load thinking; scale effort to complexity.1718## When to Plan1920- **Always plan**: multi-file changes, new features, refactors, >5 tool calls21- **Skip planning**: single-file edits, quick lookups, simple questions2223## Planning Files2425Create in project root before starting work:2627| File | Purpose | Update When |28|------|---------|-------------|29| `task_plan.md` | Phases, tasks, decisions, errors | After each phase |30| `findings.md` | Research, discoveries, code analysis | After any discovery |31| `progress.md` | Session log, test results, files changed | Throughout session |3233## Plan Template3435```markdown36# Plan: [Feature/Task Name]3738## Approach39[1-3 sentences: what and why]4041## Scope42- **In**: [what's included]43- **Out**: [what's explicitly excluded]4445## Phase 1: [Name]46**Files**: [specific files, max 5-8 per phase]47**Tasks**:48- [ ] [Verb-first atomic task] — `path/to/file.ts`49- [ ] [Next task]50**Verify**: [specific test: "POST /api/users → 201", not "test feature"]51**Exit**: [clear done definition]5253## Phase 2: [Name]54...5556## Open Questions57- [Max 3, only truly blocking unknowns]58```5960## Phase Sizing Rules6162Every phase must be **context-safe**:63- Max 5-8 files touched64- Max 2 dependencies on other phases65- Fits in one 2-4 hour session (implementation + verification + fixes)66- If a phase violates these → split it6768## Clarifying Questions6970Scale to complexity:71- Small task: 0-1 questions, assume reasonable defaults72- Medium feature: 1-2 questions on critical unknowns73- Large project: 3-5 questions (auth, data model, integrations, scope)7475Only ask if truly blocking. Make reasonable assumptions for everything else.7677## Task Rules7879- **Atomic**: one logical unit of work per task80- **Verb-first**: "Add...", "Create...", "Refactor...", "Verify..."81- **Concrete**: name specific files, endpoints, components82- **Ordered**: respect dependencies, sequential when needed83- **Verifiable**: include at least one validation task per phase8485## Context Management Rules8687| Situation | Action |88|-----------|--------|89| Starting new phase | Read task_plan.md (refresh goals in attention window) |90| After any discovery | Write to findings.md immediately |91| After completing phase | Update task_plan.md status, log to progress.md |92| After viewing image/PDF | Write findings NOW (multimodal content doesn't persist) |93| Resuming after gap | Read all planning files |94| Just wrote a file | Don't re-read it (still in context) |95| Error occurred | Log to task_plan.md, read relevant files for state |9697## Error Protocol9899```100ATTEMPT 1: Diagnose root cause → targeted fix101ATTEMPT 2: Different approach (different tool, library, method)102ATTEMPT 3: Question assumptions → search for solutions → update plan103AFTER 3 FAILURES: Escalate to user with what you tried104```105106**Never repeat the exact same failing action.** Track attempts, mutate approach.107108## Iterative Refinement109110For complex projects, iterate on the plan before implementing:1111. Draft initial plan1122. Review for gaps, missing edge cases, architectural issues1133. Revise until suggestions become incremental1144. Only then start implementation115116## 5-Question Context Check117118If you can answer these, your planning is solid:119120| Question | Source |121|----------|--------|122| Where am I? | Current phase in task_plan.md |123| Where am I going? | Remaining phases |124| What's the goal? | Approach section |125| What have I learned? | findings.md |126| What have I done? | progress.md |127128## Anti-Patterns129130| Don't | Do Instead |131|-------|------------|132| Start coding without a plan | Create task_plan.md first |133| State goals once and forget | Re-read plan before decisions |134| Hide errors and retry silently | Log errors, mutate approach |135| Keep everything in context | Write large content to files |136| Repeat failed actions | Track attempts in plan file |137| Create vague tasks ("improve X") | Concrete verb-first tasks with file paths |138| Plan phases with 12+ files | Split into 5-8 file chunks |139| Plan at 100% capacity | Budget for verification, fixes, and unknowns |
iliaal