Refactor Planner

npx skills add WST2002/claude-code-skills --skill refactor-planner

Overview

Refactoring changes structure, never behavior. Lock behavior with tests first, move in small steps that each leave the code working, and keep every step reviewable and revertible.

Method

1. State the goal in one sentence and why it pays off: "Split orders.ts (1,400 lines) so checkout and refunds can change independently."
2. Map the code: who calls the target (find usages), what it depends on, public contracts that must not change.
3. Build the safety net. Run existing tests. If the behavior being moved is not covered, add characterization tests that capture what it does today, including odd behavior.
4. Plan small steps. Each step is one known refactoring, keeps tests green, and is one commit:
   • Rename, extract function, extract module, move function, inline, introduce parameter object, replace conditional with polymorphism, extract interface at a boundary.
   • For migrations: add the new path beside the old one, move callers in batches, delete the old path last.
5. Execute step by step: change, run tests, commit. Never mix a refactor and a behavior change in one commit.
6. Finish: remove dead code, update docs, report.

Output

Before changing code, deliver the plan:

Goal: <one sentence>
Safety net: <existing tests, tests to add>
Steps:
1. <refactoring> — <files> — risk: low/medium/high
2. ...
Out of scope: <tempting changes deliberately left out>

After executing: the list of commits and the test result after the last one.

Smells and the refactoring that fixes them

Smell	Refactoring
Long function doing several things	Extract function per responsibility
File or class with many unrelated reasons to change	Split by responsibility, move functions
Same logic in several places	Extract shared function; keep it where all callers can reach it
Long parameter lists	Introduce parameter object
switch on type repeated in many places	Polymorphism or a lookup table
Deep nesting	Guard clauses, early returns
Feature envy (code that mostly uses another module's data)	Move function to that module

Common mistakes

• Big-bang rewrite in one commit that nobody can review or revert.
• Refactoring without tests, then discovering behavior changed in production.
• "While I am here" behavior changes mixed into the refactor.
• Abstracting for imagined future needs; extract only what has two real callers.
• Renaming public APIs without a deprecation path for external users.