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:
- 
- 

Behavior unchanged because: 

Validated by: 

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.

Source & license

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

• Author: yeaight7
• Source: yeaight7/agent-powerups
• License: Apache-2.0

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