Entered plan mode. Focus on exploring the codebase and designing an implementation approach without writing code.
In plan mode:
- Thoroughly explore the codebase to understand existing patterns
- Identify similar features and architectural approaches
- Consider multiple approaches and their trade-offs
- Design a concrete implementation strategy
- Write the plan and return its path
DO NOT write or edit any files yet (except the plan file). This is a read-only exploration and planning phase.
Workflow
Phase 1: Initial Understanding
Goal: Gain comprehensive understanding of the user's request.
Use only research agents — no other agent types.
-
Understand the user's request and associated code
-
Launch research agents in parallel (single message, multiple calls):
- Use
skill: 'research' for all exploration agents
- Use the cheapest model available
- 1 agent for isolated tasks with known files
- Multiple agents for uncertain scope, multiple codebase areas, or pattern discovery
- Max 3 agents — usually 1 is enough
-
Use multiple agents when:
- Task touches multiple parts of the codebase
- Large refactor or architectural change
- Many edge cases to consider
- Need to compare different approaches
Phase 2: Design
Goal: Design an implementation approach based on exploration results.
Launch 1-3 design agents in parallel:
- Default: 1 design agent for most tasks
- Skip agents: Only for trivial tasks (typo fixes, single-line changes, simple renames)
- Multiple agents: For complex tasks needing different perspectives
Example perspectives by task type:
- New feature: simplicity vs performance vs maintainability
- Bug fix: root cause vs workaround vs prevention
- Refactoring: minimal change vs clean architecture
For each agent:
- Provide comprehensive background from Phase 1
- Describe requirements and constraints
- Request a detailed implementation plan
Phase 3: Review
Goal: Review plans and ensure alignment with user's intentions.
- Read critical files identified by agents
- Verify plans align with the original request
- Do NOT call subagents here
Phase 4: Final Plan
Goal: Write the final plan. Include:
- Only the recommended approach, not alternatives
- Critical file paths to be modified
- Verification section (how to test end-to-end)
- Concise enough to scan, detailed enough to execute
Plan Structure Template
## Plan: [Feature Name]
### Summary
[1-2 sentence overview of what will be built/changed]
### Files to Modify
| File | Change |
|------|--------|
| path/to/file.ts | [what changes] |
### Implementation Steps
1. [Step 1]: [what to do, why, any gotchas]
2. [Step 2]: [what to do, why, any gotchas]
3. [Step 3]: [what to do, why, any gotchas]
### Architecture Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| [Decision] | [Choice] | [Why this over alternatives] |
### Risks & Mitigations
| Risk | Probability | Mitigation |
|------|-------------|------------|
| [Risk] | Low/Med/High | [Mitigation] |
### Verification
- [ ] [Test command / manual check]
- [ ] [Edge case to verify]
Common Planning Patterns
| Pattern | When to use |
|---|
| Surgical | Small, isolated change. Read 1-2 files, write plan in 1 message. |
| Scout | Adding to existing pattern. Find 3+ similar implementations first. |
| Architect | New feature or refactor. Full phases 1-4 with multiple agents. |
| Emergency | Production bug. Skip to fix, plan doc optional. |
Anti-Patterns
| Mistake | Fix |
|---|
| Over-planning trivial changes | Small typo? Just fix it. Plan adds no value. |
| Under-planning complex changes | New feature across 10 files? Always go through phases 1-4. |
| Skipping verification | Always include how to test the end result. |
| Too many alternatives in final plan | Choose one. Use the plan file, not a discussion document. |
| Designing without reading existing patterns | Always check 3+ similar implementations first. |
Error Handling
| Cause | Fix |
|---|
| Research subagent returns incomplete or empty results | The subagent may have hit a timeout or the codebase scope was too narrow. Re-launch with explicit file paths and a more focused query. If still empty, read the files directly. |
| Design subagent proposes a solution that contradicts codebase conventions | Subagent lacks the full context of the codebase style guide. Manually review the plan against 3+ existing implementations. Override the subagent recommendation and document the convention in the plan. |
| Plan file path conflicts with an existing file | The skill writes to a plan path that already exists (e.g., PLAN.md was already created). Append a timestamp: PLAN-20260518-143000.md. Ask user if they want to overwrite or keep both. |
| Phase 1 exploration reveals the task is trivial (single-file, single-line) | Full 4-phase planning is wasteful for a typo fix. Abort plan mode. Inform user the change is trivial and ask if they want to skip directly to implementation. |
| Plan exceeds 200 lines but user asked for concise | The plan template encourages thoroughness but the user has a scanning constraint. Collapse "Files to Modify" to a 3-column table. Collapse "Implementation Steps" to bullet points without nested details. |
| User changes requirements mid-planning (Phase 3 or 4) | The plan was built against stale requirements. Do not patch the existing plan. Return to Phase 1 with the new requirements. Archive the old plan with a deprecation comment. |
Checklist
Sources
- "The Pragmatic Programmer" by David Thomas and Andrew Hunt (Addison-Wesley, 20th Anniversary Edition, 2019) — tracer bullet development and prototyping principles
- "Software Architecture: The Hard Parts" by Neal Ford, Mark Richards, Pramod Sadalage, Zhamak Dehghani (O'Reilly, 2021) — architectural decision records and trade-off analysis
- "A Philosophy of Software Design" by John Ousterhout (Yaknyam Press, 2nd Edition, 2021) — deep module design and complexity management
- Google Design Docs culture (google.github.io/eng-practices/review/design-docs) — structured design document template and review process
- RFC (Request for Comments) process documentation (github.com/rust-lang/rfcs) — community-driven technical proposal patterns
- "Domain-Driven Design" by Eric Evans (Addison-Wesley, 2003) — bounded context mapping and ubiquitous language in planning
- Nygard, Michael T. "Release It! Design and Deploy Production-Ready Software" (Pragmatic Bookshelf, 2nd Edition, 2018) — stability patterns and failure mode planning
