Goal: Measure twice, cut once. No code is written without a plan.
Before writing any implementation plan:
- Read existing docs: Check
docs/,README.md, andVISION.md. - Trace the code: Use search tools to understand the current architecture.
- Map the problem: Identify the root cause, not just the symptom. Trace the full call chain.
- Check Knowledge: Review existing Knowledge Items (KIs) or wikis.
- Assess blast radius: Which other components, tests, or docs will this change affect?
Every non-trivial feature gets a written plan before any code changes.
- Location:
docs/plans/PLAN-{NNN}-{short-slug}.md - Registry:
docs/plans/README.md
Use the Plan Template for all new plans.
It must cover:
- Problem Statement: Why this matters.
- Proposed Changes: File-by-file impact.
- Execution Order: Priority of tasks.
- Verification: Exact steps to prove it works.
Solo Mode: For changes under 2 hours, use the Solo Plan Template — a 5-line version that captures intent without ceremony. The plan can live in a commit message or a quick
.mdfile. The point is: think before you type.
CRITICAL RULE: Always show the plan before making code changes.
- Create the plan file.
- Notify the user/lead.
- Wait for explicit approval.
- If changes are requested, update the plan and re-request approval.
- Only proceed to code when the plan is locked.
Solo Mode: You are your own approver, but the ritual still matters. Write the plan → walk away for 5 minutes → re-read it → then code. This "cool-down review" catches 80% of architecture mistakes that excitement blinds you to.
Related: 00-Mindset · 02-Execution · 04-Documentation · AI Planning · Plan Template