Refactor Planner

---
name: refactor-planner
description: Use when planning a refactor as a sequence of small, independently mergeable steps. Triggers on "refactor plan", "how to refactor", "break up this code", "extract a service".
---

# Refactor Planner

The biggest refactor failure mode is the long-lived branch that diverges from main and can never merge. The fix is to plan refactors as a series of small, independently shippable steps where main keeps working at every step.

If a step can't be merged on its own with everything still passing, it's too big.

## Required inputs

1. **Current state** — what the code looks like today, briefly
2. **Target state** — what it looks like after, in 1-3 sentences
3. **Why** — what problem this fixes (perf, testability, ownership, complexity)
4. **Constraints** — what cannot break, what cannot pause (releases, on-call rotations)
5. **Time budget** — best estimate of weeks/sprints available

If the user can't articulate why, push back. Refactors without a clear "why" become bike-sheds.

## Step planning rules

Each step must be:
1. **Mergeable on its own** — main works after the step lands
2. **Reversible** — revertible in <1 commit if it goes wrong
3. **Reviewable** — diff small enough for one engineer to review in <30 min (target <500 lines)
4. **Tested** — has its own test or a clear "covered by existing test X"
5. **Boring** — does ONE thing the title describes

If a step touches 12 files for "various improvements," split it.

## Common safe-refactor patterns

### Add then remove
1. Add the new path next to the old one
2. Migrate callers one at a time
3. Delete the old path when no callers remain

### Strangler fig (for service extraction)
1. Add the new service, no traffic
2. Route a thin slice of traffic (one endpoint, one customer)
3. Expand slice as confidence grows
4. Remove the old code path last

### Type-first
1. Add a type / interface for the new shape
2. Make existing code conform without changing behavior
3. Refactor implementation behind the type
4. Now the change is local

### Test scaffolding
1. Wrap the messy thing in characterization tests (capture current behavior)
2. Refactor with confidence — tests catch regressions
3. Replace characterization tests with proper tests once shape is clean

## Output structure

```
# Refactor: [name]

## Goal
1-3 sentences. The "why" must be visible.

## Current state
What's in place today, briefly.

## Target state
What we're moving toward.

## Steps

### Step 1: [verb-led title — "Extract pricing calc into pure function"]
**What changes**: 1-2 sentences
**Files touched**: ~3-5
**Test plan**: [what new test or what existing test covers it]
**Revertible by**: [single revert OR "cannot revert after step N because..."]
**Estimated review size**: ~150 lines

### Step 2: [...]
[Same structure]

### Step N (last)
[...]

## Out of scope
What this refactor explicitly does NOT do (so reviewers don't ask).

## Validation between steps
What to run after each step — tests, benchmarks, manual smoke check.

## Rollback strategy
How to stop mid-refactor if priorities change. Most refactor plans should be safely abandonable after step 3 with no harm.
```

## Anti-patterns

- "Big rewrite" branch that never merges
- A single "refactoring" PR with 2,000 lines of mixed structural and behavioral changes
- Step descriptions like "clean up X" — what's the actual change?
- No test plan per step — refactor without tests is a bug factory
- Steps that depend on a future step landing first — nothing should depend on the future

## Tone

- Imperative. "Step 1: extract `calculatePrice` from `Order.checkout`."
- Honest about risk. If a step is high-risk, mark it and propose a feature flag.
- Pessimistic about time. Refactors are always at least 1.5x the gut estimate.

## Output

Markdown. End with the calendar mapping: how steps fit across sprints / weeks. If the plan is >10 steps, split into phases. The user can always do half and call it a win.