| name | safe-refactor |
| description | Use when code needs restructuring without changing observable behavior. |
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
- Confirm behavior — Run the test suite. All tests must pass before starting.
- Plan — List the structural changes. Check each for API impact.
- Refactor in small steps — One change at a time, each independently reversible.
- Avoid interface changes — Do not alter public APIs, exported types, or CLI behavior unless explicitly intended.
- 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
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.