plan-first-development

Planning

Overview

Plan-first development methodology where 80%+ of time goes to planning before implementation begins. Planning tokens are cheaper than implementation tokens, and models reason better about a detailed plan that fits their context window than about a sprawling codebase.

When to use: Starting new projects, adding major features, breaking complex work into phases, resuming work after context clears, managing multi-session implementations, coordinating multiple agents on the same codebase.

When NOT to use: Quick bug fixes, one-file changes, exploratory prototyping where requirements are unknown, trivial refactors where the change is obvious.

Quick Reference

Planning Phase	Description
1. Initial plan	Write goals, intent, workflows, tech stack
2. Iterative refinement	4-5 rounds of review until suggestions plateau
3. Multi-model blend	Get competing plans, merge best-of-all-worlds
4. Convert to tasks	Self-contained tasks with dependency structure
5. Polish tasks	6+ rounds of cross-model review

Phase Type	Scope	Max Files	Duration
Infrastructure	Scaffolding, build config, deployment	3-5	1-3 hours
Database	Migrations, schema, seed data	2-4	2-4 hours
API	Routes, middleware, validation	3-6	3-6 hours
UI	Components, forms, state, styling	4-8	4-8 hours
Integration	Third-party services, webhooks	2-4	3-5 hours
Testing	E2E tests, integration tests	varies	3-6 hours

Pattern	Purpose	Key Points
When to plan vs build	Decision tree by complexity signals	Match planning depth to task complexity
Risk assessment	Probability x impact matrix	Focus on high-risk items first

Session Lifecycle	Action
Start	Read SESSION.md, check "Next Action", continue
Work	Implement, verify, debug (repeat)
Checkpoint	Git commit with structured format, update SESSION.md hash
Wrap	Update SESSION.md, git checkpoint, set concrete "Next Action"
Resume	Read SESSION.md + planning docs, continue from "Next Action"

Document	When to Generate
Implementation phases	Always -- core plan doc for every project
Session tracking	Always -- navigation hub for progress
Database schema	3+ tables
API endpoints	5+ endpoints
Architecture overview	Multiple services or complex system boundaries
Critical workflows	Complex setup steps, order-sensitive workflows

Good Plan	Great Plan
Describes what to build	Explains WHY you are building it
Lists features	Details user workflows and interactions
Mentions tech stack	Justifies tech choices with tradeoffs
Has tasks	Has tasks with dependencies and rationale
~500 lines	~3,500+ lines after refinement

Common Mistakes

Mistake	Correct Pattern
Starting implementation before planning is complete	Spend 80%+ of time on planning; finish all refinement rounds before writing code
Writing vague next actions like "continue API work"	Be specific: "Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47"
Session tracking doc over 200 lines	Collapse completed phases to summaries; reference planning docs for details
Creating phases with 10+ files	Auto-split into sub-phases of 5-8 files that fit in one 2-4 hour session
Single-round plan review	Iterate 4-5 rounds until suggestions plateau; use multi-model blending for fresh perspectives
Copying code into session docs	Reference file paths and line numbers instead of pasting code
Duplicating planning doc content in session doc	Link to sections with anchors; session doc is a navigation hub
No verification criteria on phases	Every phase needs specific, testable exit criteria (status codes, user flows, constraints)
Skeleton-first coding before a plan exists	One thorough plan beats incremental skeleton-first coding
Planning without prototyping unknown tech	Build a spike first for unfamiliar frameworks, then create the plan
Over-planning simple tasks	Match planning depth to complexity; skip for trivial work
Not validating assumptions early	Run a spike for the riskiest assumption first

Delegation

• Explore existing codebase for architecture decisions: Use Explore agent to survey file structure, patterns, and dependencies before planning
• Execute phase implementation with verification: Use Task agent to implement individual phases, run verification criteria, and create checkpoint commits
• Design architecture and decompose into phases: Use Plan agent to create implementation phases with dependency ordering and gate criteria

References

• Planning process and iterative refinement
• Session management and context tracking
• Phase-based implementation planning
• Review workflows and multi-model blending
• Decision tracking and conditional documents
• Planning document templates