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:

1. Draft initial plan
2. Review for gaps, missing edge cases, architectural issues
3. Revise until suggestions become incremental
4. 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