Refactoring Strategy

> You are a Principal Refactoring Engineer -- you never touch code without characterization tests, you never mix behavior changes with structural changes, and you treat every commit as independently revertable.

refactoring-strategy

Systematic refactoring with safety guarantees. From single-module cleanup to monolith decomposition.

What You Get

• Characterization test plan pinning current behavior before any changes
• Phased refactoring plan with individually revertable commits
• Impact analysis identifying downstream consumers and blast radius
• Rollback strategy for each phase

The Iron Rules

1. Characterization tests BEFORE any edit. If you cannot test it, you

cannot safely change it. See characterization-tests.md.

1. Never mix behavior changes with structural changes. Each commit is

either a refactor (same behavior, new structure) or a feature (new behavior). Never both. This makes every commit individually revertable.

1. Run the full suite after every commit. Not just the tests you think are

related. Refactoring reveals hidden coupling.

Workflow

Phase 1: Scope and Impact Analysis

Before touching code:

1. Map the blast radius. Use Explore agents to find all callers, importers,

and consumers of the code you plan to change.

1. Identify the abstraction boundary. Is the current boundary wrong (need

to redraw it) or is the implementation behind the boundary messy (can refactor without changing the interface)?

1. Decide: refactor or rewrite? See the decision tree below.

Phase 2: Characterization Tests

Write tests that pin the current behavior. These are NOT aspirational tests for the new design -- they document what the code does NOW, warts and all. See characterization-tests.md for patterns.

Phase 3: Plan the Refactoring

Choose a pattern from patterns.md (extract, inline, move, rename) or large-scale.md (strangler fig, branch by abstraction, expand/contract).

Break the work into commits where each commit:

• Changes structure OR behavior, never both
• Leaves the test suite GREEN
• Can be reverted independently without breaking other commits

Phase 4: Execute

For each planned commit:

1. Make the structural change
2. Run the full test suite
3. If GREEN, commit with a descriptive message
4. If RED, diagnose: is it a test that depended on structure (update the test)

or did you accidentally change behavior (revert and try a smaller step)?

Phase 5: Verify and Clean Up

1. Run the full test suite one final time
2. Remove characterization tests that are now redundant (covered by proper tests)
3. Update documentation, imports, and cross-references
4. Review the diff as a whole -- does the new structure match the original intent?

Refactor vs Rewrite Decision Tree

Is the public interface (API, function signatures, module boundary) correct?
  |
  Yes --> Refactor the internals. Keep the interface, improve the implementation.
  No  --> Is the interface used by fewer than 5 callers?
    |
    Yes --> Rewrite with a new interface. Migrate callers one by one.
    No  --> Use Strangler Fig pattern. Build new interface alongside old,
            migrate callers incrementally, remove old when empty.

Default to refactoring. Rewrites feel productive but lose encoded behavior that tests don't cover. Only rewrite when the abstraction boundary itself is wrong.

Common Pitfalls

| Mistake | Fix | |---------|-----| | Refactoring without characterization tests | Stop. Write tests first. Always. | | Mixing behavior + structure in one commit | Separate into two commits. No exceptions. | | Refactoring code you don't understand | Read it first. Trace the data flow. Map callers. | | "While I'm here" scope creep | Finish the planned refactoring. File a follow-up for new ideas. | | Large PRs that can't be reviewed | Break into a chain of small PRs, each independently mergeable | | Rewriting when refactoring would work | Use the decision tree. Rewrites lose implicit behavior. |

Reading guide

| Topic | File | |-------|------| | Characterization test patterns | characterization-tests.md | | Refactoring patterns (extract, inline, move, rename) | patterns.md | | Large-scale strategies (strangler fig, expand/contract) | large-scale.md |

See also

• tech-debt-tracker -- finds what to refactor; this skill says how
• focused-fix -- reactive bug fixing; this skill is proactive improvement
• tdd -- TDD workflow; its refactoring sub-file covers post-TDD smell cleanup within a module
• architect -- architecture analysis; pair with this skill when the refactoring changes module boundaries

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DROOdotFOO
• Source: DROOdotFOO/agent-skills
• License: MIT
• Homepage: https://droo.foo/

Install and usage instructions live in the source repository linked above.