plan

What this skill does

# 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

```markdown
# [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](planning-guide.md)