Planning Mode
Enter planning mode to research, analyze, and document a considered approach before implementation. Output a plan document to .work/plans/backlog/<name>.md.
Planning Workflow
1. Understand the Request
Clarify what needs planning:
- What problem are we solving?
- What constraints exist (time, tech stack, team familiarity)?
- Is there prior art in this codebase?
Ask clarifying questions before researching.
2. Research the Codebase
Investigate relevant areas:
- Existing patterns and conventions
- Related implementations
- Database schema and data models
- API contracts and boundaries
- Configuration and environment requirements
Use codebase_search, grep, and read_file to gather context.
3. Research Technologies
When introducing or evaluating technologies:
- Fetch current documentation using available tools
- Check compatibility with existing stack (Node.js, TypeScript, pnpm, etc.)
- Evaluate maturity, maintenance status, bundle size implications
4. Analyze Trade-offs
For each approach considered:
- Benefits: What problems does it solve well?
- Drawbacks: What complexity or limitations does it introduce?
- Risks: What could go wrong? Migration paths?
- Alternatives: What else was considered and why not?
5. Write the Plan
Create .work/plans/backlog/<descriptive-name>.md with:
# Plan: <Title>
**Status:** Draft | Review | Approved
**Created:** <date>
**Author:** <who requested>
## Context
What triggered this plan? Link to conversations, issues, or user requests.
## Problem Statement
One paragraph: what problem are we solving and why it matters.
## Research Findings
### Codebase Analysis
- Relevant existing patterns
- Files/modules that will be affected
- Current state vs desired state
### Technology Evaluation
- Options considered
- Compatibility notes
- Documentation links
## Proposed Approach
Clear description of the recommended solution.
### Why This Approach
- Key benefits
- How it fits existing patterns
### Trade-offs Accepted
- Known limitations
- Complexity being introduced
### Alternatives Considered
| Approach | Pros | Cons | Why Not |
|----------|------|------|---------|
| ... | ... | ... | ... |
## Open Questions
- Unresolved decisions needing input
- Areas requiring more research
- Questions for the team
## Next Steps
- [ ] Specific actionable items
- [ ] Who needs to review/approve
- [ ] Dependencies or blockers
Output Guidelines
- Be concise: Developers will read this. Respect their time.
- Be specific: Link to actual files, functions, line numbers.
- Be honest: Surface unknowns and risks clearly.
- Be decisive: Recommend an approach, don't just list options.
When Planning Completes
After writing the plan:
- Summarize the recommendation to the user
- Highlight key trade-offs and open questions
- Ask if they want to proceed, modify, or research further
- If approved, the plan can be used to generate tasks via the
taskskill