# Refactor Planner

Analyze messy code and produce a safe, incremental refactor plan with risk assessment, rollback strategy, and a test-first checklist.

## Quick Reference

# 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

| 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