Create Plan

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

Step 2: Validate Plan Completeness

Checklist:

• [ ] 100% of original issue/task requirements mapped to plan steps
• [ ] Overview section complete with requirements table
• [ ] Context & motivation clear
• [ ] CLAUDE.md compliance documented
• [ ] Existing types analyzed
• [ ] Impact analysis thorough
• [ ] Implementation steps detailed and ordered
• [ ] Every requirement from issue appears in at least one step
• [ ] 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

• 100% ISSUE COVERAGE - Plan MUST address every requirement from original issue
• 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
• NEVER SKIP REQUIREMENT - Every issue requirement MUST have a plan step
• 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

[Feature Name]

Summary

[2-3 sentences: What feature is being added and why it's needed]

Type

Feature

Status

Todo

---

Context

Why This Feature?

[Business or technical motivation]

Current State

[What exists now that this feature builds upon or replaces]

Desired State

[What will exist after implementation]

---

CLAUDE.md Compliance

Naming Conventions

• [Relevant naming rules from CLAUDE.md]

Architecture Requirements

• [Relevant architectural patterns]

Type Requirements

• [Type-related guidelines]

Other Guidelines

• [Any other applicable rules]

---

Existing Types

Types to Reuse

• TypeName from path/to/file.ts - Purpose

Types to Create

• NewType - Why needed (only if no existing type works)

Type Guidelines

• ❌ No any types
• ❌ No unknown without justification
• ✅ Strict typing everywhere

---

Impact Analysis

Files to Modify

• path/to/file.ts - What changes and why

Files to Create

• path/to/new-file.ts - Purpose and justification

Files to Delete

• path/to/old-file.ts - Reason for removal

Dependencies Affected

• [What depends on changed code]

Breaking Changes

• [Any breaking changes and mitigation]

---

Implementation Steps

Step 1: [First Task]

File: path/to/file.ts Action: [Specific action] Why: [Reason] Details:

• [Implementation detail]

Step 2: [Next Task]

[Continue pattern]

---

REMOVAL SPECIFICATION

Code to Remove

From path/to/file.ts

• Lines X-Y: [code snippet]
• Why: [Reason]
• Replacement: [What replaces it]
• Dependencies: [What uses it]

Files to Delete

• path/to/old-file.ts
• Why: [Reason]
• Replacement: [Where functionality moved]
• Dependencies: [What imports it]

Removal Checklist

• [ ] All deprecated functions removed
• [ ] All old files deleted
• [ ] All imports updated
• [ ] All references updated
• [ ] No dead code remains

---

Anti-Patterns to Avoid

❌ Never Include:

• Feature flags for this change
• Fallback to old implementation
• Migration period code
• Gradual rollout mechanisms

✅ Always Do:

• Complete, clean implementation
• Full removal of old code
• All changes at once

---

Validation Criteria

Pre-Implementation

• [ ] CLAUDE.md reviewed
• [ ] Existing types identified
• [ ] Impact analyzed
• [ ] Naming verified

Post-Implementation

• [ ] All steps completed
• [ ] REMOVAL SPEC satisfied
• [ ] TypeScript passes
• [ ] Linting passes
• [ ] Tests pass
• [ ] No any types
• [ ] CLAUDE.md compliant

Fix: [Bug Description]

Summary

[2-3 sentences: What bug is being fixed and its impact]

Type

Fix

Status

Todo

---

Context

Bug Description

[Detailed description of the bug]

Current Behavior

[What happens now (incorrect behavior)]

Expected Behavior

[What should happen (correct behavior)]

Root Cause

[Technical reason for the bug]

---

CLAUDE.md Compliance

Naming Conventions

• [Any relevant naming rules]

Architecture Requirements

• [Relevant architectural patterns]

Type Requirements

• [Type-related guidelines]

---

Existing Types

Types to Reuse

• TypeName from path/to/file.ts - Purpose

Type Issues Contributing to Bug

• [Any type-related causes of the bug]

Type Improvements

• [How to strengthen typing to prevent similar bugs]

---

Impact Analysis

Files to Modify

• path/to/buggy-file.ts - Fix implementation

Root Cause Location

• path/to/file.ts:line - Where bug originates

Affected Code Paths

• [What execution paths hit this bug]

Side Effects

• [Any other code affected by the fix]

---

Implementation Steps

Step 1: [Fix Root Cause]

File: path/to/file.ts Action: [Specific fix] Why: [How this addresses root cause] Details:

• [Implementation detail]

Step 2: [Update Related Code]

[Address any side effects]

Step 3: [Add Safeguards]

[Prevent similar bugs in future]

---

REMOVAL SPECIFICATION

Code to Remove

From path/to/file.ts

• Lines X-Y: [buggy code]
• Why: Contains the bug
• Replacement: Step 1 implementation
• Dependencies: [What calls this]

Removal Checklist

• [ ] Buggy code removed
• [ ] All instances of bug pattern fixed
• [ ] No related issues remain

---

Anti-Patterns to Avoid

❌ Never Include:

• Workarounds instead of proper fix
• Keeping buggy code with flags
• Temporary patches
• "Good enough" solutions

✅ Always Do:

• Fix root cause properly
• Remove buggy code completely
• Add prevention measures
• Verify complete fix

---

Validation Criteria

Pre-Implementation

• [ ] Bug reproduced
• [ ] Root cause identified
• [ ] Fix approach validated
• [ ] Side effects considered

Post-Implementation

• [ ] Bug no longer reproduces
• [ ] All test cases pass
• [ ] TypeScript passes
• [ ] Linting passes
• [ ] No regressions
• [ ] Prevention measures added

Test Cases

• [ ] Original bug scenario
• [ ] Edge cases
• [ ] Related scenarios
• [ ] Regression tests

Refactor: [What's Being Refactored]

Summary

[2-3 sentences: What code is being refactored and why]

Type

Refactor

Status

Todo

---

Context

Why Refactor?

[Technical debt, maintainability issues, or architectural improvements needed]

Current Problems

[Specific issues with current implementation]

Desired Outcome

[How code will be better after refactoring]

---

CLAUDE.md Compliance

Naming Conventions

• [Relevant naming rules]

Architecture Requirements

• [Architectural patterns to follow]

Type Requirements

• [Type guidelines]

---

Existing Types

Types to Reuse

• TypeName from path/to/file.ts - Usage

Types to Consolidate

• [Types that can be merged or simplified]

Type Guidelines

• ❌ No any types
• ❌ Eliminate unknown where possible
• ✅ Strengthen typing

---

Impact Analysis

Files to Modify

• path/to/file.ts - Refactoring changes

Files to Consolidate

• Merge file1.ts + file2.ts → file-new.ts

Files to Delete

• path/to/redundant-file.ts - No longer needed

Dependencies Affected

• [What needs updating due to refactor]

Breaking Changes

• [Any API changes, how to handle]

---

Implementation Steps

Step 1: [Preparation]

File: path/to/file.ts Action: [What to do] Why: [Reason] Details:

• [Detail]

Step 2: [Core Refactoring]

[Continue pattern]

Step 3: [Cleanup]

[Remove old code]

---

REMOVAL SPECIFICATION

Code to Remove

From path/to/file.ts

• Lines X-Y: [old implementation]
• Why: Being replaced by refactored version
• Replacement: Step X
• Dependencies: [What calls this]

Files to Delete

• path/to/old-pattern-file.ts
• Why: Consolidated into new structure
• Replacement: [Where functionality moved]

Removal Checklist

• [ ] Old implementations removed
• [ ] Redundant files deleted
• [ ] Dead code eliminated
• [ ] All references updated

---

Anti-Patterns to Avoid

❌ Never Include:

• Keeping old code "temporarily"
• Both old and new implementations running
• Gradual migration code
• Backward compatibility layers

✅ Always Do:

• Complete refactor in one pass
• Delete old code immediately
• Update all usages together

---

Validation Criteria

Pre-Implementation

• [ ] Current code fully understood
• [ ] Better pattern identified
• [ ] All usages found
• [ ] Impact assessed

Post-Implementation

• [ ] All steps completed
• [ ] Old code removed
• [ ] TypeScript passes
• [ ] Linting passes
• [ ] Tests pass
• [ ] Behavior unchanged (unless intentional)
• [ ] Code quality improved