Incremental Refactoring Planner
Plan a refactor as safe, shippable steps — each one leaving the code working.
Plans a refactoring as a sequence of small, independently shippable steps where the code works after every step. Includes risk assessment per step, the tests to add first, and explicit criteria for aborting — the discipline that separates refactoring from rewriting.
The prompt
Variables to fill in: {{current}}{{goal}}{{constraints}}
You are a pragmatic tech lead planning a refactor. Given the current state and the goal, produce an incremental plan.
Requirements for the plan:
- Each step must leave the system working and shippable — no step may depend on a future step to compile or pass tests.
- Before step 1: list the characterization tests to add FIRST that pin current behavior (name the specific behaviors to pin).
- For each step: what changes, why it's safe, estimated size (S/M/L), and what could go wrong.
- Identify the point of no return, if any — the step after which rolling back costs more than finishing.
- Abort criteria: 2-3 discoveries during execution that should pause the refactor for a rethink (e.g. "step 3 reveals the module has hidden consumers").
- If the goal is achievable without touching more than ~30% of the affected code, prefer that plan over a purer but larger one.
Current state (code, architecture description, or pain points):
{{current}}
Refactoring goal:
{{goal}}
Constraints (deadlines, team size, deploy frequency):
{{constraints}}How to use
- 1Describe pain points honestly in {{current}} — 'nobody understands this module' is useful signal, paste key code if possible.
- 2Actually write the characterization tests before starting; every step's safety argument depends on them.
- 3Ship each step separately. The plan's whole value is destroyed by batching steps into one big PR.
- 4Revisit the abort criteria when surprised — they're pre-made decisions for exactly that moment.
Examples
Extracting a service from a monolith module
Input
Current: 3k-line 'billing.py' mixing Stripe calls, invoice logic, and email sending; goal: isolate Stripe behind an interface; constraints: 2 devs, weekly deploys.
Output
**Tests first**: pin invoice total calculation for the 4 plan types, webhook idempotency behavior, and the refund path... **Step 1 (S)**: introduce PaymentProvider protocol + StripeProvider implementing it, delegating to existing functions — safe: pure addition... **Point of no return**: step 4 (migrating webhook handlers)...
Pro tips
- Ask 'what's the 20% version of this plan' when the full plan exceeds your constraint budget.
Frequently asked questions
How is this different from just asking the model to refactor the code?+
Direct refactoring produces a big diff you have to trust wholesale. A plan of shippable steps keeps you in control, works with code too large to paste, and survives contact with surprises — which every real refactor meets.
Can a coding agent execute the plan?+
Yes — feed steps one at a time to Claude Code or a similar agent, with the characterization tests as the gate for each. Pair it with a CLAUDE.md from our library for repo conventions.