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 1: Understand the Request

• Review the report or analysis that triggered this plan
• 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

# [Plan Title]

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

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

## 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/ directory
• Use .todo.md extension
• Include ALL required sections above
• Be thorough - never skip items

Step 2: Validate Plan Completeness

Checklist:

• Overview section complete
• Context & motivation clear
• CLAUDE.md compliance documented
• Existing types analyzed
• Impact analysis thorough
• Implementation steps detailed and ordered
• REMOVAL SPECIFICATION complete
• Anti-patterns section included
• Validation criteria defined
• No migration/fallback mechanisms
• No temporary file names
• No any or unknown types planned

Step 3: Review Against Guidelines

Double-check:

• ✅ Follows naming conventions from CLAUDE.md
• ✅ Uses existing types where possible
• ✅ Single responsibility maintained
• ✅ Complete removal spec included
• ✅ No migration code planned
• ✅ All steps are specific and actionable
• ✅ No items skipped or rushed

Step 4: Final Audit Recommendation

Before finalizing, consider:

• Should specific areas be audited more deeply?
• Are there unknowns that need investigation?
• Is more context needed before implementation?

If yes, recommend using the audit skill for those areas.

Phase 5: Report to User

Provide summary:

# Plan Created: [plan-name]

## Location
`.plans/[plan-name].todo.md`

## Summary
[Brief description of what the plan covers]

## Key Points
- [Important aspect 1]
- [Important aspect 2]
- [Important aspect 3]

## Files Affected
- X files to modify
- Y files to create
- Z files to delete

## REMOVAL SPEC
- [Summary of what will be removed]

## Ready to Implement
The plan is complete and ready for implementation. All required sections are included, CLAUDE.md compliance is verified, and the removal specification is thorough.

## Next Steps
Review the plan and begin implementation when ready.

Critical Principles

• NEVER RUSH - Thorough planning prevents bad implementations
• NEVER SKIP AUDIT - Always understand the codebase first
• NEVER CREATE MIGRATIONS - Replace completely, not gradually
• NEVER USE TEMPORARY NAMES - Use final, proper names from the start
• NEVER SKIP REMOVAL SPEC - Track what must be deleted
• ALWAYS USE EXISTING TYPES - Create new types only when necessary
• ALWAYS FOLLOW CLAUDE.MD - Read and apply all guidelines
• ALWAYS BE SPECIFIC - Vague steps lead to bad implementations
• ALWAYS THINK HOLISTICALLY - Consider full impact of changes
• COMPLETENESS OVER SPEED - A complete plan prevents future problems

Templates

See templates/ directory for:

• feature-plan-template.md - Template for new features
• refactor-plan-template.md - Template for refactoring
• fix-plan-template.md - Template for bug fixes