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

| 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

• [ ] 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EliasOulkadi
• Source: EliasOulkadi/shokunin
• License: MIT
• Homepage: https://eliasoulkadi.github.io/shokunin/

Install and usage instructions live in the source repository linked above.