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. ## Procedure 1. Run the *Goal Quality Gate* on the stated goal. 2. Pick the path per *When to Plan*: full plan, flat list, or skip. 3. For a full plan, scaffold `.plan/` via [init-plan.sh](./scripts/init-plan.sh). 4. Write the plan per the *Plan Template*, applying the quality, sizing, and task rules. 5. Run the *Verify* checklist against the finished plan. 6. Offer the *Execution Handoff* choice. ## Goal Quality Gate Run this gate before *When to Plan* below — a weak goal wastes tokens on any path and produces an unverifiable result. Answer these five questions first: 1. **What concrete thing will be true when this is done?** (named artifact, system state verifiable without knowing the changed component's internals, or user-visible behavior — not "improve X" or "investigate Y") 2. **What evidence will prove it?** (specific test, command, screenshot, metric — not "looks right") 3. **What quantitative or binary threshold defines success?** (p95 < 250ms; `npm run test:checkout` passes; `gh pr view 123` shows no unresolved threads) 4. **What scope boundaries matter?** (which files/modules/environments are in scope; which are explicitly not) 5. **What should cause the agent to stop and ask?** (which decis...