| name | planning |
| description | Create and refine implementation plans. Use when breaking down features, discussing architecture, or preparing work before coding. Plans focus on approach and decisions, not code.
|
Planning
Plans are thinking tools, not specifications. They capture approach and decisions to guide implementation.
Plan Template
# <name> Plan
**Status:** draft | ready | executing | done
**Created:** <date>
## Goal
<!-- One sentence: what are we building/solving? -->
## Context
<!-- Why now? Constraints? Dependencies? -->
## Approach
<!-- High-level strategy, not code. How will we solve this? -->
## Key Decisions
<!-- Architecture choices, tradeoffs, alternatives considered -->
## Tasks
<!-- Ordered list of what to do. Focus on WHAT not HOW -->
- [ ] Task 1
- [ ] Task 2
## Open Questions
<!-- Unresolved issues to figure out -->
## Notes
<!-- Refinement session notes -->
Refinement Principles
- One question at a time — Don't overwhelm with multiple questions
- Explore options — Propose 2-3 approaches with tradeoffs, recommend one
- Capture incrementally — Write decisions to file as agreed
- Surface unknowns — Note open questions that need answers
- Exit gracefully — When user says "looks good" or conversation ends naturally
Task Philosophy
Tasks should be goals, not implementation details:
| ✅ Good | ❌ Bad |
|---|
| Add caching layer | Create Redis client in src/cache.ts |
| Refactor auth to use JWT | Replace line 45-60 with jwt.sign() call |
| Add user preferences API | Create file at src/api/preferences.ts with... |
| Improve error handling | Add try-catch to functions X, Y, Z |
Tasks should be:
- Actionable — Clear what "done" looks like
- High-level — Describe what, not how
- Independently valuable — Each delivers something useful
- Revertable — Can undo if needed
Plan Quality
A plan is ready when it has:
- Clear goal (one sentence)
- Defined approach (strategy, not code)
- Key decisions documented
- Ordered task list
- Open questions identified (if any)
Content Rules
- No code snippets — Describe what, not how
- Approach over implementation — Strategy, not syntax
- Decisions over details — Capture why, not exact how
- Living document — Update as understanding evolves
