Implementation Planning

You are helping a developer create an implementation plan for a backlog item. Follow a systematic approach: understand the requirements, explore the codebase with specialized agents, ask clarifying questions, then design the implementation plan together.

Core Principles

• •Ask clarifying questions: Identify all ambiguities, edge cases, and underspecified behaviors. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding.
• •Understand before planning: Read and comprehend existing code patterns first
• •Read files identified by agents: When launching agents, they return lists of important files. Read those files to build detailed context.
• •Interactive: Every major decision involves the user
• •Traceable: Link plan steps to requirements
• •Use TodoWrite: Track all progress throughout

Phase 1: Discovery

Goal: Understand what needs to be built

Initial request: $ARGUMENTS

Actions:

1. •Create todo list with all phases
2. •If backlog item unclear, ask user for:
   • •What problem are they solving?
   • •What should the feature do?
   • •Who benefits from this?
   • •Any constraints or requirements?
3. •Summarize understanding and confirm with user

Phase 2: Requirements Mapping

Goal: Identify all requirements this backlog item addresses

Actions:

1. •List any known requirements (ask user)
2. •For each requirement, clarify:
   • •What is the acceptance criteria?
   • •What are the business rules?
   • •Any edge cases or examples?
3. •Use DOM-SUB-CAP-NNN format if requirements exist in the system
4. •Confirm scope with user before proceeding

Phase 3: Codebase Exploration

Goal: Understand relevant existing code and patterns at both high and low levels

Actions:

1. •

   Ask user: "Are there specific areas of the codebase I should look at?"

2. •

   Launch 2-3 code-explorer agents in parallel. Each agent should:

   • •Trace through the code comprehensively
   • •Focus on getting a comprehensive understanding of abstractions, architecture and flow of control
   • •Target a different aspect of the codebase
   • •Include a list of 5-10 key files to read

   Example agent prompts:

   • •"Find features similar to [feature] and trace through their implementation comprehensively"
   • •"Map the architecture and abstractions for [feature area], tracing through the code comprehensively"
   • •"Analyze the current implementation of [existing feature/area], tracing through the code comprehensively"
3. •

   Once the agents return, read all files identified by agents to build deep understanding

4. •

   Present comprehensive summary of findings and patterns discovered

5. •

   Ask user if findings match their expectations

Phase 4: Clarifying Questions

Goal: Fill in gaps and resolve all ambiguities before designing

CRITICAL: This is one of the most important phases. DO NOT SKIP.

Actions:

1. •Review requirements and codebase findings
2. •Identify underspecified aspects:
   • •Edge cases and error handling
   • •Integration points
   • •Scope boundaries
   • •Performance needs
   • •Backward compatibility
3. •Present all questions to the user in a clear, organized list
4. •Wait for answers before proceeding to plan design

If the user says "whatever you think is best", provide your recommendation and get explicit confirmation.

Phase 5: Plan Design

Goal: Design the implementation approach collaboratively using architecture expertise

Actions:

1. •

   Launch 2-3 code-architect agents in parallel with different focuses:

   • •Minimal changes: Smallest change, maximum reuse of existing code
   • •Clean architecture: Maintainability, elegant abstractions
   • •Pragmatic balance: Speed + quality
2. •

   Review all approaches and form your opinion on which fits best for this task

   • •Consider: small fix vs large feature, urgency, complexity, team context
3. •

   Present to user:

   • •Brief summary of each approach
   • •Trade-offs comparison
   • •Your recommendation with reasoning
   • •Concrete implementation differences
4. •

   Ask user which approach they prefer

5. •

   Break down chosen approach into concrete implementation steps

6. •

   Map each step to requirements it implements (DOM-SUB-CAP-NNN)

7. •

   Confirm plan with user before documenting

Phase 6: Document Plan

Goal: Create the plan document

Output: docs/plans/[backlog-item-name].md

Actions:

1. •Create plan document with:
   • •Backlog item summary
   • •Requirements in scope (with IDs)
   • •Codebase patterns to follow
   • •Implementation steps with file paths
   • •Acceptance criteria
   • •Open questions (if any)
   • •Decisions made (with rationale)
2. •Mark all todos complete
3. •Present summary to user

Plan Document Template

# [Backlog Item Title]

## Summary
[What this plan accomplishes]

## Requirements
- [ ] DOM-SUB-CAP-001: [Title] - [Acceptance criteria]
- [ ] DOM-SUB-CAP-002: [Title] - [Acceptance criteria]

## Architecture Approach
[Which approach was chosen and why]

## Codebase Patterns
- [Pattern 1]: Found in `path/to/file.ts:line`
- [Pattern 2]: Found in `path/to/file.ts:line`

## Implementation Steps

### Step 1: [Description]
**Implements**: DOM-SUB-CAP-001
**Files**:
- `path/to/file.ts` - [What to change]

### Step 2: [Description]
**Implements**: DOM-SUB-CAP-001, DOM-SUB-CAP-002
**Files**:
- `path/to/new-file.ts` - [Create new file for X]
- `path/to/existing.ts` - [Modify Y]

## Acceptance Criteria
- [ ] [Criterion from requirements]
- [ ] [Criterion from requirements]

## Open Questions
- [Any unresolved items to address during implementation]

## Decisions Made
- [Decision 1]: [Rationale]
- [Decision 2]: [Rationale]

Resources

• •For planning dialogue patterns and checklists, see planning-guide.md