This prompt is adapted from Matt Pocock's request-refactor-plan skill, reshaped as a copyable prompt for Claude Code.

Refactoring without a plan leads to one of two outcomes: either you get stuck halfway with broken code and no clear path forward, or you accidentally change behavior while "just cleaning things up." This prompt forces a disciplined approach — understand the problem, scope the work, check test coverage, then break it into the smallest possible commits.

The key principle (from Martin Fowler): make each refactoring step so small that the program is always working.

The prompt

I want to refactor [describe what you want to change]. Help me plan this properly before we touch any code.

## Step 1: Understand the current state

Read the relevant code and answer:
- What does this code do today? (behavior, not implementation)
- Who calls it? What depends on it?
- What are the pain points? (why does this need refactoring?)

## Step 2: Explore alternatives

Before committing to an approach, consider at least two different ways to refactor this. For each option:
- What changes?
- What stays the same?
- What's the risk?

Present the options and let me choose.

## Step 3: Check test coverage

Look at existing tests for the code being refactored:
- What behaviors are covered?
- What's NOT covered that we're about to change?
- Do we need to add tests BEFORE refactoring to protect existing behavior?

If coverage is insufficient, we add tests first — as a separate commit — before changing anything.

## Step 4: Plan tiny commits

Break the refactor into the smallest possible commits. Each commit must:
- Leave the codebase in a working state (tests pass, app runs)
- Change one thing (rename, extract, move, inline — not all at once)
- Have a clear description of what changed and why

Format each commit as:
1. **What**: the specific change
2. **Why**: what this step accomplishes
3. **Verify**: how to confirm it worked (test command, manual check)

## Step 5: Scope boundaries

Explicitly state:
- What IS in scope for this refactor
- What is NOT in scope (even if tempting)
- What follow-up work this might reveal

We do not expand scope mid-refactor. If we discover something that needs changing, we note it and address it separately.

When to use it

• Before renaming or restructuring modules
• Before extracting shared code from duplicated logic
• Before changing data structures or interfaces that multiple files depend on
• When you're about to say "while I'm in here, I should also..."

Why tiny commits matter

Large refactoring commits are where bugs hide. When a commit does five things and something breaks, you don't know which of the five caused it. Tiny commits give you:

• Bisectability — git bisect can pinpoint exactly which change broke things
• Revertability — if one step goes wrong, you revert that step, not the whole refactor
• Reviewability — each commit in a PR tells a clear story

Tips

• If Claude tries to do the whole refactor in one shot, stop it. The discipline of tiny commits is the whole point.
• The "check test coverage" step often reveals that you need to write tests before refactoring. This feels slow but prevents the worst outcome: changing behavior you didn't intend to change.
• Keep a running list of "not in scope" discoveries. These become follow-up issues, not scope creep.