planning

# 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 ```markdown # 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 ...