Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, clean up legacy code, eliminate code smells, or improve code maintainability. This skill guides through a phased approach with research, planning, and safe incremental implementation.
A systematic approach to refactoring code based on Martin Fowler's Refactoring: Improving the Design of Existing Code (2nd Edition). This skill emphasizes safe, incremental changes backed by tests.
"Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code yet improves its internal structure." — Martin Fowler
Phase 1: Research & Analysis
↓
Phase 2: Test Coverage Assessment
↓
Phase 3: Code Smell Identification
↓
Phase 4: Refactoring Plan Creation
↓
Phase 5: Incremental Implementation
↓
Phase 6: Review & Iteration
Before starting, clarify:
Present findings to user:
"Refactoring without tests is like driving without a seatbelt." — Martin Fowler
Tests are the key enabler of safe refactoring. Without them, you risk introducing bugs.
Check for existing tests
# Look for test files
find . -name "*test*" -o -name "*spec*" | head -20
Run existing tests
# JavaScript/TypeScript
npm test
# Python
pytest -v
# Java
mvn test
Check coverage (if available)
# JavaScript
npm run test:coverage
# Python
pytest --cov=.
If tests exist and pass:
If tests are missing or incomplete: Present options:
If tests are failing:
For each function being refactored, ensure tests cover:
Use the "red-green-refactor" cycle:
Symptoms of deeper problems in code. They're not bugs, but indicators that the code could be improved.
See references/code-smells.md for the complete catalog.
| Smell | Signs | Impact |
|---|---|---|
| Long Method | Methods > 30-50 lines | Hard to understand, test, maintain |
| Duplicated Code | Same logic in multiple places | Bug fixes needed in multiple places |
| Large Class | Class with too many responsibilities | Violates Single Responsibility |
| Feature Envy | Method uses another class's data more | Poor encapsulation |
| Primitive Obsession | Overuse of primitives instead of objects | Missing domain concepts |
| Long Parameter List | Methods with 4+ parameters | Hard to call correctly |
| Data Clumps | Same data items appearing together | Missing abstraction |
| Switch Statements | Complex switch/if-else chains | Hard to extend |
| Speculative Generality | Code "just in case" | Unnecessary complexity |
| Dead Code | Unused code | Confusion, maintenance burden |
Automated Analysis (if scripts available)
python scripts/detect-smells.py <file>
Manual Review
Prioritization Focus on smells that:
Present to user:
For each smell, select an appropriate refactoring from the catalog.
See references/refactoring-catalog.md for the complete list.
| Code Smell | Recommended Refactoring(s) |
|---|---|
| Long Method | Extract Method, Replace Temp with Query |
| Duplicated Code | Extract Method, Pull Up Method, Form Template Method |
| Large Class | Extract Class, Extract Subclass |
| Feature Envy | Move Method, Move Field |
| Primitive Obsession | Replace Primitive with Object, Replace Type Code with Class |
| Long Parameter List | Introduce Parameter Object, Preserve Whole Object |
| Data Clumps | Extract Class, Introduce Parameter Object |
| Switch Statements | Replace Conditional with Polymorphism |
| Speculative Generality | Collapse Hierarchy, Inline Class, Remove Dead Code |
| Dead Code | Remove Dead Code |
Use the template at templates/refactoring-plan.md.
For each refactoring:
CRITICAL: Introduce refactoring gradually in phases.
Phase A: Quick Wins (Low risk, high value)
Phase B: Structural Improvements (Medium risk)
Phase C: Architectural Changes (Higher risk)
Before implementation:
"Change → Test → Green? → Commit → Next step"
For each refactoring step:
Pre-check
Make ONE small change
Verify
If tests pass (green)
If tests fail (red)
Each commit should be:
Example commit messages: