Refactoring Surgeon Agent Skill

Refactoring Surgeon

Expert code refactoring specialist focused on improving code quality without changing behavior.

Quick Start

• Ensure tests exist - Never refactor without a safety net
• Identify the smell - Name the specific code smell you're addressing
• Make small changes - One refactoring at a time, commit frequently
• Run tests after each change - Behavior must remain identical
• Don't add features - Refactoring ≠ enhancement
• Document significant changes - Explain the "why" for future maintainers

Core Capabilities

| Category | Techniques |

|----------|------------|

| Extraction | Extract Method, Extract Class, Extract Interface |

| Movement | Move Method, Move Field, Inline Method |

| Simplification | Replace Conditional with Polymorphism, Decompose Conditional |

| Organization | Introduce Parameter Object, Replace Magic Numbers |

| Legacy Migration | Strangler Fig, Branch by Abstraction, Parallel Change |

Code Smells Reference

Bloaters

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│    Long Method      │    │    Large Class      │    │   Long Parameter    │
│  > 20 lines?        │    │  > 200 lines?       │    │       List          │
│  → Extract Method   │    │  → Extract Class    │    │  → Parameter Object │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

OO Abusers

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  Switch Statements  │    │   Refused Bequest   │    │   Parallel          │
│  Type-checking?     │    │  Unused inheritance?│    │   Hierarchies       │
│  → Polymorphism     │    │  → Delegation       │    │  → Move Method      │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

Change Preventers

┌─────────────────────┐    ┌─────────────────────┐
│  Divergent Change   │    │  Shotgun Surgery    │
│  One class, many    │    │  One change, many   │
│  reasons to change? │    │  classes affected?  │
│  → Extract Class    │    │  → Move/Inline      │
└─────────────────────┘    └─────────────────────┘

Reference Examples

Complete refactoring examples in ./references/:

| File | Pattern | Use Case |

|------|---------|----------|

| extract-method.ts | Extract Method | Long methods → focused functions |

| replace-conditional-polymorphism.ts | Replace Conditional | switch/if → polymorphic classes |

| introduce-parameter-object.ts | Parameter Object | Long params → structured objects |

| strangler-fig-pattern.ts | Strangler Fig | Legacy code → gradual migration |

Anti-Patterns (10 Critical Mistakes)

1. Big Bang Refactoring

Symptom: Rewriting entire modules in one massive change

Fix: Strangler fig pattern, small incremental changes with tests

2. Refactoring Without Tests

Symptom: Changing structure without test coverage

Fix: Write characterization tests first, add coverage for affected areas

3. Premature Abstraction

Symptom: Creating generic frameworks "for future flexibility"

Fix: Wait for three concrete examples before abstracting (Rule of Three)

4. Renaming Without IDE Support

Symptom: Find-and-replace that misses occurrences

Fix: Use IDE refactoring tools, search for usages first

5. Mixing Refactoring and Features

Symptom: Adding new functionality while restructuring

Fix: Separate commits - refactor first, then add features

6. Ignoring Code Reviews

Symptom: Large refactoring PRs that are hard to review

Fix: Small, focused PRs with clear commit messages

7. Over-Abstracting

Symptom: Three layers of abstraction for a simple operation

Fix: YAGNI - start concrete, abstract when patterns emerge

8. Incomplete Refactoring

Symptom: Starting Extract Method but leaving partial duplication

Fix: Complete the refactoring or revert - no half-measures

9. Refactoring Production During Incidents

Symptom: "I'll just clean this up while I'm here..."

Fix: Never refactor during incidents - fix the bug, create a ticket

10. Not Measuring Improvement

Symptom: Refactoring without knowing if it helped

Fix: Track metrics: complexity, test coverage, build time

Safety Checklist

Before Refactoring:

• [ ] Code compiles/runs successfully
• [ ] All tests pass
• [ ] Test coverage is adequate for area being refactored
• [ ] Commit current state (can rollback)

During Refactoring:

• [ ] Make small, incremental changes
• [ ] Run tests after each change
• [ ] Keep behavior identical
• [ ] Don't add features while refactoring

After Refactoring:

• [ ] All tests still pass
• [ ] No new warnings/errors
• [ ] Code is more readable
• [ ] Complexity metrics improved
• [ ] Document significant changes

Quality Checklist

• [ ] No behavior changes (tests prove this)
• [ ] Improved readability
• [ ] Reduced complexity (cyclomatic, cognitive)
• [ ] Better adherence to SOLID principles
• [ ] Removed duplication (DRY)
• [ ] More testable code
• [ ] Clear naming
• [ ] Appropriate abstractions (not over-engineered)

Validation Script

Run ./scripts/validate-refactoring.sh to check:

• Test coverage presence
• Code smell indicators
• Duplication patterns
• Complexity metrics
• SOLID violations
• Refactoring safety (git, uncommitted changes)

External Resources

• Refactoring.Guru
• Martin Fowler's Refactoring Catalog
• Working Effectively with Legacy Code