Create Implementation Plan

Instructions

Create a detailed, high-quality implementation plan in .plans/ directory that adheres to strict quality standards and provides complete guidance for implementation.

Phase 1: Understanding & Validation

Step 0: Extract Original Issue/Task Requirements (MANDATORY)

CRITICAL: Before creating any plan, extract ALL requirements from the original issue/task.

# If triggered by a GitHub issue
gh issue view <number>

Create exhaustive requirements list:

• Every functional requirement stated
• Every acceptance criterion listed
• Every edge case mentioned
• Every error handling requirement
• Any implicit requirements (derive from context)

Store this list - the plan MUST cover 100% of these requirements.

Step 1: Understand the Request

• Review the report or analysis that triggered this plan
• Map each requirement from Step 0 to plan items
• Identify the type of plan needed:
  • Feature: New functionality
  • Refactor: Code restructuring
  • Fix: Bug fix or issue resolution
  • Enhancement: Improvement to existing feature

Step 2: Audit the Codebase

CRITICAL: Never create a plan without thorough codebase understanding

For each item in the report, perform comprehensive analysis:

1. Use the audit skill if needed for deep investigation
2. Identify affected files - Which files will change?
3. Find existing patterns - How is similar code structured?
4. Check CLAUDE.md files - What are the rules for this area?
5. Analyze types - What existing types can be reused?
6. Identify dependencies - What depends on what we're changing?
7. Find naming patterns - How should new files be named?

DO NOT SKIP THIS STEP - Rushed plans lead to bad implementations

Step 3: CLAUDE.md Compliance Check

Read ALL relevant CLAUDE.md files in:

• Project root
• Affected directories
• Related modules

Extract requirements:

• Naming conventions
• Architecture patterns
• Type requirements
• File organization rules
• Code style standards

Phase 2: Plan Structure & Naming

Step 1: Choose Plan Name

Format: [descriptive-name].todo.md

Rules:

• Use kebab-case
• Be specific and descriptive
• Reflect actual work (not vague like "improvements")
• Examples:
  • implement-user-authentication.todo.md ✅
  • refactor-database-layer.todo.md ✅
  • new-features.todo.md ❌ (too vague)

Step 2: Determine File Names for Implementation

CRITICAL RULES:

• ❌ NEVER create migration files like foo_v2.ts, foo-new.ts, foo-enhanced.ts
• ❌ NEVER use temporary naming like simple-*.ts, temp-*.ts
• ✅ ALWAYS use proper, final names from the start
• ✅ ALWAYS follow existing naming patterns in the directory
• ✅ ALWAYS check CLAUDE.md for naming requirements

Process:

1. Identify existing file naming patterns
2. Check CLAUDE.md for conventions
3. Choose names that fit the pattern
4. If unsure, analyze similar existing files
5. Plan to replace existing files directly (not create duplicates)

Phase 3: Plan Content - Required Sections

Create plan document with ALL of the following sections:

1. Overview & Issue Coverage

# [Plan Title]

## Summary
[2-3 sentences explaining what and why]

## Type
[Feature | Refactor | Fix | Enhancement]

## Source Issue/Task
[Link to GitHub issue or task description]

## Original Requirements (100% Coverage Required)

**ALL requirements from source issue/task that this plan MUST address:**

| # | Requirement | Plan Step(s) |
|---|-------------|--------------|
| 1 | [Requirement from issue] | Step X |
| 2 | [Requirement from issue] | Step Y, Z |
| 3 | [Requirement from issue] | Step W |

**Coverage Check**: X of X requirements mapped to plan steps (must be 100%)

## Status
Todo (will be renamed to .done.md when complete)

2. Context & Motivation

## Context
[Why is this needed? What problem does it solve?]

## Current State
[What exists now? What are the limitations?]

## Desired State
[What will exist after? What improvements will we gain?]

3. CLAUDE.md Compliance

## CLAUDE.md Requirements

### Naming Conventions
- [List relevant naming rules from CLAUDE.md]

### Architecture Requirements
- [List relevant architectural rules]

### Type Requirements
- [List type-related rules]

### Other Guidelines
- [Any other relevant rules]

4. Existing Types Analysis

## Existing Types

### Types to Reuse
- `TypeName` from `path/to/file.ts` - [what it represents]
- [List ALL types that can be reused]

### Types to Create
- `NewTypeName` - [what it will represent, why needed]
- [Only create if NO existing type works]

### Type Guidelines
- ❌ NEVER use `any`
- ❌ NEVER use `unknown` (unless absolutely necessary with justification)
- ✅ ALWAYS prefer existing types
- ✅ ALWAYS use strict typing

5. Impact Analysis

## Impact Analysis

### Files to Modify
- `path/to/file1.ts` - [what changes, why]
- `path/to/file2.ts` - [what changes, why]

### Files to Create
- `path/to/newfile.ts` - [purpose, why not existing file]

### Files to Delete
- `path/to/oldfile.ts` - [why removing, what replaces it]

### Dependencies Affected
- [List what depends on changed code]
- [How will dependencies be updated?]

### Breaking Changes
- [List any breaking changes]
- [How will they be handled?]

6. Implementation Steps

## Implementation Steps

Each step should be:
- Specific and actionable
- Single responsibility
- Ordered correctly (dependencies first)

### Step 1: [Descriptive Title]
**File**: `path/to/file.ts`
**Action**: [What to do]
**Why**: [Why this step]
**Details**:
- [Specific implementation detail]
- [Another detail]

### Step 2: [Next Step]
[Same structure]

[Continue for all steps]

7. REMOVAL SPECIFICATION ⚠️

## REMOVAL SPECIFICATION

**CRITICAL**: This section tracks OLD code that must be REMOVED.

### Code to Remove

#### From `path/to/file1.ts`
- **Lines X-Y**: `function oldFunction() {...}`
  - **Why removing**: Replaced by newFunction
  - **Replacement**: Step 3 in implementation
  - **Dependencies**: Used by A, B, C (all updated in steps 5, 6, 7)

#### File to Delete: `path/to/old-file.ts`
- **Why removing**: Functionality moved to new-file.ts
- **Replacement**: Step 2 creates replacement
- **Dependencies**: Imported by X, Y, Z (all updated in steps 8, 9, 10)

### Removal Checklist
- [ ] All deprecated functions removed
- [ ] All old files deleted
- [ ] All imports updated
- [ ] All references updated
- [ ] No dead code remains

**VERIFICATION**: At completion, grep for old symbols to ensure complete removal.

8. Anti-Patterns to Avoid

## Anti-Patterns to Avoid

❌ **NEVER** include:
- Migration mechanisms (gradual rollout, feature flags for this)
- Fallback mechanisms (keeping old code "just in case")
- Risk mitigation (running old and new in parallel)
- Backward compatibility layers (unless external API)
- Temporary bridges between old and new

✅ **ALWAYS** instead:
- Replace completely and cleanly
- Make all necessary changes at once
- Remove old code immediately
- Trust the plan and execute fully

**Why**: Half-migrations leave bad code in the codebase forever.

9. Validation Criteria

## Validation Criteria

### Pre-Implementation Checklist
- [ ] All CLAUDE.md files reviewed
- [ ] All existing types identified
- [ ] All affected files identified
- [ ] All naming follows patterns
- [ ] Impact fully analyzed

### Post-Implementation Checklist
- [ ] All steps completed
- [ ] All old code removed (per REMOVAL SPEC)
- [ ] TypeScript compiles (`tsc --noEmit`)
- [ ] Linting passes (`npm run lint`)
- [ ] Tests pass (if applicable)
- [ ] No `any` or `unknown` types added
- [ ] CLAUDE.md compliance verified
- [ ] Single responsibility maintained

Phase 4: Plan Creation & Validation

Step 1: Write the Plan

• Create file in .plans/ directo