# 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 ``` **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 | Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | Breaking change to public API | Medium | High | Add adapter layer | | Missing test coverage | High | High | Write tests first (blocker) | | Concurrent modification by team | Low | Medium | Use a feature branch | | Performance regression | Low | High | Benchmark before and after | --- ### 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

Input: Code to refactor

function processOrder(order) {
  if (order.type === 'A') {
    // 30 lines of logic
  } else if (order.type === 'B') {
    // 40 lines of logic
  } else if (order.type === 'C') {
    // 25 lines of logic
  }
}

Output: Refactor plan

Smell: Long if-else chain (strategy)

Plan (3 steps, no behaviour change)

1. Extract handlers
   processOrderA(order) { ... }
   processOrderB(order) { ... }
   processOrderC(order) { ... }

2. Build dispatch map
   const handlers = {
     A: processOrderA,
     B: processOrderB,
     C: processOrderC
   }

3. Replace function body
   const h = handlers[order.type]
   if (!h) throw Error(order.type)
   return h(order)