| name | plan-mode |
| description | Holistic, system-aware planning before implementing non-trivial tasks. Use when the task involves new features, architectural decisions, multi-file changes, unclear requirements, or multiple valid approaches. Triggers on "/plan", "plan this", "design an approach", "let's plan first". |
For non-trivial implementation tasks, plan before you code. Treat every change as a system change, not an isolated patch. Find the smallest implementation that remains coherent with the architecture, lifecycle, and future evolution of the system.
Planning Doctrine
- Think broadly, implement narrowly. Analyze the surrounding system before deciding where the change belongs.
- Every change has system implications. Consider data flow, ownership of state, interfaces, lifecycle, failure modes, and future extension.
- Prefer authoritative, derivable designs. If state can be derived from persisted state or existing abstractions, prefer that over inventing transient duplicates.
- Choose the smallest coherent solution. Do not default to the smallest local patch if it distorts the architecture.
- Expand scope only when it simplifies the system. Not for speculative improvement.
- Keep the language current. When a plan coins or clarifies a domain term, or settles a directional decision, update
CONTEXT.md in the same change.
Steps
- Explore. Read relevant files; trace the end-to-end flow; identify the current source of truth, state ownership, and lifecycle (trigger, processing, completion, failure, retry, cleanup). Search for prior art. Do not implement yet.
- Clarify. Ask the user about ambiguities — behavior, edge cases, failure handling, tradeoffs — before committing to an approach.
- Design. Compare the most direct implementation against the most system-coherent one. Answer explicitly: What is the source of truth before/after? What new state or invariants does this introduce? Does it duplicate logic anywhere? What is the smallest solution that keeps the system coherent?
- Review. Re-read the critical files your design depends on to verify assumptions. Confirm the design covers loading, in-progress, completion, failure, retry, and cleanup.
- Present. Write the plan (structure per
docs/plans/README.md) to PLAN.md or docs/plans/<feature>.md and wait for approval.
- Implement and verify. Track progress per item, then run the plan's verification steps.
