safe-refactoring

Safe Refactoring

What This Skill Enables

Agents with this skill can improve code structure -- readability, modularity, performance -- while guaranteeing that external behavior stays identical. Without it, agents tend to rewrite large sections at once, introduce subtle regressions, and produce diffs that are impossible for humans to review confidently. Safe refactoring turns a risky "big bang" rewrite into a chain of small, provably correct transformations.

Core Competencies

1. Decide Whether to Refactor at All

Not every piece of ugly code needs attention right now. Before touching anything, answer these questions:

Question	If "No", stop here
Is this code on the path of the current task?	Do not refactor drive-by style.
Do passing tests already cover the behavior?	Write tests first (see competency 2).
Is the improvement worth the review cost?	A rename across 200 files is noisy for little gain.
Is there a deadline within hours?	Ship first, refactor in a follow-up branch.

Refactoring that is not motivated by a concrete upcoming change is speculative. Avoid it.

2. Lock Behavior with Tests Before Changing Structure

The "lock then change" pattern is non-negotiable:

Step 1 -- Write or confirm tests that cover the code you are about to move.
Step 2 -- Run the full relevant test suite. It must pass.
Step 3 -- Perform ONE refactoring move (see competency 3).
Step 4 -- Run the suite again. It must still pass.
Step 5 -- Commit with a single-purpose message.
Step 6 -- Repeat from Step 3 for the next move.

If no tests exist and writing them is impractical, add at minimum a characterization test: call the function with known inputs and assert on the current outputs, even if those outputs look wrong. The point is to detect change, not to validate correctness.

3. Use Named Refactoring Moves

Each commit should contain exactly one kind of transformation. Mixing moves makes regressions hard to bisect.

Move	When to Use	Key Risk
Extract Function	A block inside a function has a clear name and purpose.	Getting the parameter list wrong; forgetting closures.
Inline Function	A wrapper adds no clarity and just indirects.	Callers may depend on the wrapper's name in tests or logs.
Rename	A name is misleading or does not match domain language.	Must update every reference, including strings and config.
Move to Module	A function lives in the wrong file or layer.	Import paths change; circular dependencies may surface.
Simplify Conditional	Nested if/else can be replaced with guard clauses or a lookup table.	Subtle short-circuit logic may be intentional.