Refactor Planner

Purpose: Analyze a code file, module, or system component and produce a safe, incremental refactor plan with risk assessment, rollback strategy, and a test-first validation checklist. Prevents big-bang rewrites that break production.

Invocation

/refactor <file-or-description>

Examples:

• /refactor src/lib/auth.ts
• /refactor The checkout flow uses a 400-line switch statement with no error handling

Analysis Steps

Step 1: Diagnose Current State

Identify code smells present:

• Long methods: functions > 50 lines
• Deep nesting: conditionals > 3 levels deep
• God object: class or module doing too many things
• Duplicated logic: same pattern repeated 3+ times
• Magic numbers/strings: unnamed constants
• Missing error handling: silent failures, swallowed exceptions
• Coupling: this code is hard to test in isolation because it depends on X

Map dependencies:

• What calls this code?
• What does it call?
• What would break if its interface changed?

Assess test coverage:

• Is this code protected by tests?
• If NO: tests must be written BEFORE refactoring begins

Step 2: Define Target State

• What will the code look like after refactoring?
• What pattern or principle does this refactor apply?
  • Extract Method, Extract Class, Strategy Pattern, Repository Pattern, etc.
• What concrete metrics improve?
  • Fewer lines, reduced cyclomatic complexity, better separation of concerns

Step 3: Risk Assessment

Step 4: Implementation Plan

Produce a numbered task list — each step independently verifiable:

[ ] 0. PREREQUISITE: Write tests covering current behavior (if missing)
[ ] 1. [Smallest safe change] — run tests, must pass
[ ] 2. [Next change] — run tests, must pass
[ ] 3. [Next change] — run tests, must pass
...
[ ] N. Delete dead code confirmed unreachable after refactor
[ ] N+1. Update documentation and comments

Step 5: Rollback Plan

• How to revert if something breaks in production?
• Is this behind a feature flag? (recommended for risky refactors)
• What is the blast radius if it fails? (1 endpoint, 1 user flow, entire app?)

Output Format

## Refactor Plan: [Module/File Name]

### Current State
[Code smells identified, complexity metrics]

### Target State
[What it looks like after, patterns applied]

### Risk Assessment
[Table]

### Prerequisites
[Tests that must exist before starting]

### Implementation Steps
[Numbered checklist]

### Rollback Strategy
[How to revert]

### Definition of Done
- [ ] All pre-existing tests still pass
- [ ] New tests cover the refactored logic
- [ ] No public API surface changed (or migration provided)
- [ ] Code reviewed by one other engineer

Rules

• Tests before refactoring is non-negotiable — stop if coverage is missing and say so
• Each step must pass tests independently — no "it'll work when step 5 is done"
• Never rename a public API without a deprecation period
• Prefer 10 small safe steps over 1 big clever change
• If the refactor requires more than 500 lines changed: propose splitting into phases