---
name: gh-refactor-plan
description: "Produces a structured plan for refactoring a file, module, or system before touching a line of code."
---
# /gh-refactor-plan

Refactors done without a plan create more mess than they clean up. You start extracting a function, realise it needs a new abstraction, add a layer, and end up with a 1000-line PR that's impossible to review. A plan takes 10 minutes. An unplanned refactor takes days and introduces bugs.

Produce a structured refactor plan for the code described in this conversation.

**What's wrong with the current code**
Name the specific problems — not "it's messy" but: this function does 4 things, this logic is duplicated in 3 places, this module is 800 lines because it owns too many responsibilities. Be precise about what makes it hard to work with.

**What the refactored state looks like**
Describe the target state: what will the structure be, what are the new boundaries, what does each piece own? Don't write code — describe the shape.

**The sequence of changes**
Break the refactor into ordered steps where each step leaves the code working. Refactors that can't be done incrementally are risky — flag them. For each step:
- What changes
- What stays the same (behaviour must be preserved)
- How to verify it still works after this step

**What must not change**
The external behaviour: inputs, outputs, side effects, error conditions. List the invariants that the refactor must preserve. These become your test criteria.

**Tests to write first**
Before moving code, list the tests that will catch regressions. If good tests already exist, name them. If they don't, write them before refactoring — not after.

**Risk assessment**
What's the highest-risk step? What could go wrong? Are there callers or consumers that will need updating?

Rules:
- Each step must be independently committable and reviewable
- If the refactor requires changing behaviour to work, that's a separate PR — not part of this refactor
- If you can't describe the target state clearly, the refactor isn't ready to start
- Prefer many small PRs over one large one — each step should be mergeable independently