| name | refactoring |
| description | Systematic code refactoring to improve design without changing behavior.
Activates when code structure needs improvement without behavior change,
including during the refactor phase of TDD cycles.
|
Refactoring Skill
Core Principle
Refactoring targets the structural mechanism that generates code smells, not individual smell instances. If you find the same smell in multiple places, the fix is to change the pattern that produces them, not to fix each instance independently.
Prerequisites
Do NOT refactor when:
- Tests are failing or missing
- You do not understand the code
- While adding new features simultaneously
Refactoring Protocol
Step 0: Research
Before refactoring — research is mandatory:
- Research the canonical pattern or design for this type of code using Tier 1 and Tier 2 sources
- Compare the current implementation against reference implementations
- Understand why the current design exists before changing it
Step 1: Verify Readiness
- All tests pass
- Test coverage is adequate for the area being changed
- You understand what the code does and why
- You have a specific improvement goal
- Changes are version controlled
Step 2: Identify the Smell
Common code smells grouped by the mechanism that generates them:
Bloaters (code grew without structural discipline):
- Long Method (>20 lines), Large Class (>300 lines)
- Long Parameter List (>3 params), Data Clumps
Change Preventers (coupling prevents isolated changes):
- Divergent Change, Shotgun Surgery, Parallel Inheritance
Dispensables (things that should not exist):
- Duplicate Code, Dead Code, Speculative Generality
Couplers (inappropriate dependencies):
- Feature Envy, Inappropriate Intimacy, Message Chains
Step 3: Choose the Refactoring
Select the smallest refactoring that improves the smell:
- Extract/Inline: Method, Variable, Class
- Rename: Variable, Method, Class
- Move: Method, Field, Statements
- Organize Data: Replace Primitive with Object, Introduce Parameter Object
- Simplify Conditionals: Decompose, Consolidate, Replace with Polymorphism
- Simplify Method Calls: Add/Remove Parameter, Separate Query from Modifier
Step 4: Execute Mechanically
- Make one structural change
- Run tests immediately
- If tests fail: REVERT. If the failure reveals a pre-existing latent bug (not caused by the refactoring), invoke the debugging protocol before continuing the refactoring cycle.
- If tests pass: continue
- Repeat with next small change
One refactoring at a time. Do not batch.
Step 5: Verify
After each refactoring:
- All tests still pass
- Behavior is unchanged
- Code is measurably better
- No new warnings or errors
- Add a recurrence guard to prevent the smell from being reintroduced
