eliasoulkadi/shokunin/plan

Entered plan mode. Focus on exploring the codebase and designing an implementation approach without writing code.

In plan mode:

1. Thoroughly explore the codebase to understand existing patterns
2. Identify similar features and architectural approaches
3. Consider multiple approaches and their trade-offs
4. Design a concrete implementation strategy
5. 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.

1. Understand the user's request and associated code

1. 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

1. 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.

1. Read critical files identified by agents
2. Verify plans align with the original request
3. 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

Anti-Patterns

Error Handling

Checklist

• [ ] Codebase explored before writing the plan — dependencies, conventions, patterns identified
• [ ] All edge cases and failure modes documented, not just happy path
• [ ] Estimations include testing, documentation, and verification time
• [ ] Dependencies and risks explicitly called out
• [ ] Plan is reviewable independently — enough context for another developer to evaluate

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