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

Playground

<span style='color:#8b949e'> if (order.type === 'A') {</span> <span style='color:#8b949e'> // 30 lines of logic</span> <span style='color:#8b949e'> } else if (order.type === 'B') {</span> <span style='color:#8b949e'> // 40 lines of logic</span> <span style='color:#8b949e'> } else if (order.type === 'C') {</span> <span style='color:#8b949e'> // 25 lines of logic</span> <span style='color:#8b949e'> }</span> <span style='color:#8b949e'>}</span></pre></div><div class='panel'><div class='label'>Output: Refactor plan</div><pre><span style='color:#58a6ff'>Smell: Long if-else chain (strategy)</span>

<span style='color:#58a6ff'>Plan (3 steps, no behaviour change)</span>

<span style='color:#8b949e'>1. Extract handlers</span> <span style='color:#3fb950'> processOrderA(order) { ... }</span> <span style='color:#3fb950'> processOrderB(order) { ... }</span> <span style='color:#3fb950'> processOrderC(order) { ... }</span>

<span style='color:#8b949e'>2. Build dispatch map</span> <span style='color:#3fb950'> const handlers = {</span> <span style='color:#3fb950'> A: processOrderA,</span> <span style='color:#3fb950'> B: processOrderB,</span> <span style='color:#3fb950'> C: processOrderC</span> <span style='color:#3fb950'> }</span>

<span style='color:#8b949e'>3. Replace function body</span> <span style='color:#3fb950'> const h = handlers[order.type]</span> <span style='color:#3fb950'> if (!h) throw Error(order.type)</span> <span style='color:#3fb950'> return h(order)</span></pre></div></div></body></html>