Refactoring

Refactoring

Use when behavior must remain the same while improving structure, readability, or testability.

Prerequisites: Tests exist or you can add characterization tests to lock behavior.

When to Use

• Behavior must remain the same
• Code is hard to read, too long, deeply nested, or duplicated
• Small changes are risky because logic is entangled
• You want to enable safer changes later

Skip if: you are changing behavior or adding features, there is no safety net and you cannot add characterization tests, or the issue is purely formatting or linting.

Quick Reference

• Define invariants for inputs, outputs, and side effects
• Ensure a safety net with tests or characterization checks
• Apply the smallest possible refactor step
• Verify after each step
• Stop once the code is clear enough

Smell to Refactor

Delegate

• Use test-writer agent to add characterization tests when no safety net exists
• Use blueprinting skill for multi-step refactors that need sequencing
• Use researching skill when the right approach is unclear
• Use code-reviewer agent to verify after refactoring

Pipeline: refactoring → code-review

Core Pattern

• Scope: pick the smallest slice that matters
• Lock behavior: tests, snapshots, or golden outputs
• Micro refactors: extract function or variable, rename for intent, split responsibilities, replace nested conditionals with guard clauses
• Verify: run checks after each step
• Stop: avoid polishing beyond the goal

Output

Before refactoring:

• Target files
• Invariants
• Safety net

After refactoring:

• What changed structurally
• What stayed the same
• Remaining risks or TODOs

Common Mistakes

• Mixing refactors with feature changes
• Large diffs without checkpoints
• Skipping the safety net and guessing behavior
• Renaming without improving structure