safe-refactor

Purpose

Restructure code in small, safe steps while preserving all externally observable behavior. Prevents refactor regressions where behavior silently changes.

When to Use

• Code needs structural improvement but its public API must remain unchanged.
• Naming, organization, or duplication needs cleanup after a feature is complete.
• Technical debt needs reduction without introducing risk.

Do not use this skill if there are no existing tests — write tests first.

Inputs

• Code to refactor.
• Existing test suite (required).
• Optional: specific goals (extract function, rename module, remove duplication).

Workflow

1. Confirm behavior — Run the test suite. All tests must pass before starting.
2. Plan — List the structural changes. Check each for API impact.
3. Refactor in small steps — One change at a time, each independently reversible.
4. Avoid interface changes — Do not alter public APIs, exported types, or CLI behavior unless explicitly intended.
5. Validate after each step — Re-run targeted tests after each meaningful change.

Output

Changed:
- <structural change 1>
- <structural change 2>

Behavior unchanged because: <reasoning>

Validated by: <test commands run>

Verification

• Tests pass before starting
• Each step is small and independently reversible
• No unintended API or interface changes introduced
• Tests pass after each meaningful step
• Final test suite fully green

Failure Modes

• Missing tests — Stop. Write tests before refactoring. Behavior cannot be verified otherwise.
• Silent API change — If a refactor touches public interfaces, stop and confirm this is intentional.
• Bundled unrelated changes — Keep each step focused. Mixed changes make rollback and blame impossible.