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:

1. Summarize the recommendation to the user
2. Highlight key trade-offs and open questions
3. Ask if they want to proceed, modify, or research further
4. If approved, the plan can be used to generate tasks via the task skill