Refactorer
Overview
The Refactorer skill provides a disciplined, step-by-step approach to improving the internal structure of code while preserving its observable behavior. It covers the most impactful refactoring patterns — including Extract Function, DRY, SOLID principles, and replacing conditionals with polymorphism — along with a decision framework for knowing when to refactor versus when to rewrite. Every refactoring step is backed by tests to ensure nothing breaks.
When to Use
- Code is difficult to read, understand, or explain to a colleague
- The same logic appears in two or more places (DRY violation)
- A function or class has grown too large and handles too many concerns
- Adding a new feature requires touching many unrelated parts of the codebase
- Technical debt has accumulated to the point of slowing down delivery
- Code review consistently raises the same structural feedback
When NOT to Use
- The code is throwaway/prototype quality and will be replaced soon
- You don't have tests and can't add them before refactoring (too risky)
- The behavior itself is wrong — fix the bug first, then refactor
- You are under a tight deadline — schedule refactoring as deliberate work
- You're tempted to rewrite in a new language or framework (that's not refactoring)
Quick Reference
| Pattern |
When to Apply |
| Extract Function |
Function body > 20 lines; logic block has a clear name |
| Extract Class |
Class has > 1 responsibility; fields cluster into subgroups |
| Rename |
Name is misleading, abbreviated, or doesn't match intent |
| DRY / Extract Common |
Same logic copied in 2+ places |
| Replace Magic Number |
Unexplained literals; use named constants |
| Guard Clause |
Deeply nested if/else; flip condition to return early |
| Replace Conditional with Polymorphism |
Long if/switch on type; open/closed principle |
| Introduce Parameter Object |
Function takes 4+ related params; group into a struct/dataclass |
| Move Method |
Method uses another class's data more than its own |
| Decompose Conditional |
Complex boolean expression; extract to named predicate function |
Instructions
Ensure test coverage before touching code
- Run the existing test suite. It must be green before you start.
- If coverage is low, write characterization tests (tests that capture current behavior) before refactoring.
- Commit the tests separately so the refactoring diff is clean.
Identify the smell — Choose the most impactful problem to fix first:
- God Class: one class that does everything
- Long Method: function spans more than 20–30 lines
- Duplicated Code: same or nearly same logic in multiple places
- Feature Envy: a method that uses another class's data extensively
- Primitive Obsession: using raw strings/ints where a domain type should exist
- Shotgun Surgery: one change requires edits across many files
Apply refactoring patterns incrementally
- Make one refactoring at a time. Run tests after each step.
- Never mix refactoring with behavior changes in the same commit.
- Use your IDE's automated refactoring tools (rename, extract, move) when available — they are safer than manual edits.
Refactor vs. Rewrite decision
- Refactor when: the core logic is correct, tests exist, and the issues are structural.
- Rewrite when: the approach is fundamentally wrong, the code can't be tested, or it would take longer to refactor than to rewrite safely.
- The "strangler fig" pattern — incrementally replacing a module while both versions run — is often better than a big-bang rewrite.
Verify behavior is unchanged
- Run the full test suite after each change.
- If you introduced a regression,
git stash or revert to the last green state immediately.
- For critical paths, add integration or end-to-end tests before and after.
Commit with intent
- Each commit should do one logical refactoring: "Extract
calculateDiscount from processOrder"
- Never combine a refactoring commit with a feature commit.
Examples
Example 1: Refactor a God Class
Input:
class OrderProcessor:
def __init__(self, db, email_client, stripe_client):
self.db = db
self.email = email_client
self.stripe = stripe_client
def process(self, user_id, cart):
# Validate cart
if not cart or len(cart) == 0:
raise ValueError("Cart is empty")
for item in cart:
if item['quantity'] <= 0:
raise ValueError(f"Invalid quantity for {item['name']}")
# Calculate total
subtotal = sum(i['price'] * i['quantity'] for i in cart)
tax = subtotal * 0.08
total = subtotal + tax
# Charge payment
charge = self.stripe.charge(user_id, total)
if not charge['success']:
raise RuntimeError("Payment failed")
# Save order
order = {'user_id': user_id, 'total': total, 'items': cart}
order_id = self.db.insert('orders', order)
# Send confirmation
user = self.db.find('users', user_id)
self.email.send(user['email'], f"Order {order_id} confirmed!")
return order_id
Output (refactored):
# cart_validator.py
class CartValidator:
def validate(self, cart):
if not cart:
raise ValueError("Cart is empty")
for item in cart:
if item['quantity'] <= 0:
raise ValueError(f"Invalid quantity for {item['name']}")
# pricing.py
class PricingCalculator:
TAX_RATE = 0.08
def calculate_total(self, cart):
subtotal = sum(i['price'] * i['quantity'] for i in cart)
return subtotal * (1 + self.TAX_RATE)
# payment_service.py
class PaymentService:
def __init__(self, stripe_client):
self.stripe = stripe_client
def charge(self, user_id, amount):
charge = self.stripe.charge(user_id, amount)
if not charge['success']:
raise RuntimeError("Payment failed")
# order_repository.py
class OrderRepository:
def __init__(self, db):
self.db = db
def save(self, user_id, total, cart):
return self.db.insert('orders', {'user_id': user_id, 'total': total, 'items': cart})
# order_processor.py — now thin orchestrator
class OrderProcessor:
def __init__(self, validator, pricing, payment, repo, notifier):
self.validator = validator
self.pricing = pricing
self.payment = payment
self.repo = repo
self.notifier = notifier
def process(self, user_id, cart):
self.validator.validate(cart)
total = self.pricing.calculate_total(cart)
self.payment.charge(user_id, total)
order_id = self.repo.save(user_id, total, cart)
self.notifier.confirm(user_id, order_id)
return order_id
Each class now has a single responsibility and can be tested in isolation.
Example 2: Extract repeated logic and apply Guard Clauses
Input:
function getDisplayName(user) {
if (user !== null && user !== undefined) {
if (user.firstName !== null && user.firstName !== undefined) {
if (user.lastName !== null && user.lastName !== undefined) {
return user.firstName + ' ' + user.lastName;
} else {
return user.firstName;
}
} else {
if (user.email !== null && user.email !== undefined) {
return user.email;
} else {
return 'Anonymous';
}
}
} else {
return 'Anonymous';
}
}
Output (refactored):
// Step 1: Apply guard clauses to flatten nesting
// Step 2: Extract predicate helper
// Step 3: Use nullish coalescing / optional chaining (ES2020+)
function getDisplayName(user) {
if (!user) return 'Anonymous';
if (user.firstName && user.lastName) return `${user.firstName} ${user.lastName}`;
if (user.firstName) return user.firstName;
return user.email ?? 'Anonymous';
}
Reduced from 20 lines to 5. Logic is identical but immediately readable.
Best Practices
- The Golden Rule: never change behavior and structure in the same commit
- Always start from a green test suite — refactoring without tests is rewriting under the illusion of safety
- Prefer small, frequent refactoring to large, infrequent rewrites
- Use your IDE's rename/extract tools instead of manual search-and-replace
- Read Refactoring by Martin Fowler for the canonical catalog of patterns
- When in doubt, extract a function — small, named functions are almost always better
Common Mistakes
- Refactoring and adding features at the same time (mixing concerns in a commit)
- Refactoring without tests — impossible to verify behavior is preserved
- Extracting too early (premature abstraction) before patterns are clear
- Renaming things inconsistently (rename in one place, miss others)
- Treating "rewrite in a cleaner way" as refactoring when the logic changes
- Gold plating — refactoring to perfection when good enough is ready to ship
Tips & Tricks
- Run your test suite in watch mode while refactoring so failures are instant
git commit --amend or git rebase -i let you clean up refactoring commits before pushing
- The "rule of three": tolerate duplication once, extract on the third occurrence
- IDE shortcuts (IntelliJ
Ctrl+Alt+M, VS Code refactor menu) are faster and safer than manual edits
- Leave code cleaner than you found it — the "boy scout rule" applied per PR
Related Skills
1---2name: refactorer3description: "Use this skill when improving the structure, clarity, or design of existing code without changing its behavior. Trigger phrases: 'clean up this code', 'this is messy', 'refactor this', 'apply SOLID principles'. Not for adding new features or fixing bugs."4version: 1.0.05author: community6tags: [coding, refactoring, clean-code, patterns]7license: MIT8metadata:9 source: https://skillmd.com/skills/xcrrr/refactorer10---1112# Refactorer1314## Overview15The Refactorer skill provides a disciplined, step-by-step approach to improving the internal structure of code while preserving its observable behavior. It covers the most impactful refactoring patterns — including Extract Function, DRY, SOLID principles, and replacing conditionals with polymorphism — along with a decision framework for knowing when to refactor versus when to rewrite. Every refactoring step is backed by tests to ensure nothing breaks.1617## When to Use18- Code is difficult to read, understand, or explain to a colleague19- The same logic appears in two or more places (DRY violation)20- A function or class has grown too large and handles too many concerns21- Adding a new feature requires touching many unrelated parts of the codebase22- Technical debt has accumulated to the point of slowing down delivery23- Code review consistently raises the same structural feedback2425## When NOT to Use26- The code is throwaway/prototype quality and will be replaced soon27- You don't have tests and can't add them before refactoring (too risky)28- The behavior itself is wrong — fix the bug first, then refactor29- You are under a tight deadline — schedule refactoring as deliberate work30- You're tempted to rewrite in a new language or framework (that's not refactoring)3132## Quick Reference33| Pattern | When to Apply |34|---------|--------------|35| Extract Function | Function body > 20 lines; logic block has a clear name |36| Extract Class | Class has > 1 responsibility; fields cluster into subgroups |37| Rename | Name is misleading, abbreviated, or doesn't match intent |38| DRY / Extract Common | Same logic copied in 2+ places |39| Replace Magic Number | Unexplained literals; use named constants |40| Guard Clause | Deeply nested if/else; flip condition to return early |41| Replace Conditional with Polymorphism | Long if/switch on type; open/closed principle |42| Introduce Parameter Object | Function takes 4+ related params; group into a struct/dataclass |43| Move Method | Method uses another class's data more than its own |44| Decompose Conditional | Complex boolean expression; extract to named predicate function |4546## Instructions47481. **Ensure test coverage before touching code**49 - Run the existing test suite. It must be green before you start.50 - If coverage is low, write characterization tests (tests that capture current behavior) before refactoring.51 - Commit the tests separately so the refactoring diff is clean.52532. **Identify the smell** — Choose the most impactful problem to fix first:54 - **God Class**: one class that does everything55 - **Long Method**: function spans more than 20–30 lines56 - **Duplicated Code**: same or nearly same logic in multiple places57 - **Feature Envy**: a method that uses another class's data extensively58 - **Primitive Obsession**: using raw strings/ints where a domain type should exist59 - **Shotgun Surgery**: one change requires edits across many files60613. **Apply refactoring patterns incrementally**62 - Make one refactoring at a time. Run tests after each step.63 - Never mix refactoring with behavior changes in the same commit.64 - Use your IDE's automated refactoring tools (rename, extract, move) when available — they are safer than manual edits.65664. **Refactor vs. Rewrite decision**67 - **Refactor** when: the core logic is correct, tests exist, and the issues are structural.68 - **Rewrite** when: the approach is fundamentally wrong, the code can't be tested, or it would take longer to refactor than to rewrite safely.69 - The "strangler fig" pattern — incrementally replacing a module while both versions run — is often better than a big-bang rewrite.70715. **Verify behavior is unchanged**72 - Run the full test suite after each change.73 - If you introduced a regression, `git stash` or revert to the last green state immediately.74 - For critical paths, add integration or end-to-end tests before and after.75766. **Commit with intent**77 - Each commit should do one logical refactoring: "Extract `calculateDiscount` from `processOrder`"78 - Never combine a refactoring commit with a feature commit.7980## Examples8182### Example 1: Refactor a God Class8384**Input:**85```python86class OrderProcessor:87 def __init__(self, db, email_client, stripe_client):88 self.db = db89 self.email = email_client90 self.stripe = stripe_client9192 def process(self, user_id, cart):93 # Validate cart94 if not cart or len(cart) == 0:95 raise ValueError("Cart is empty")96 for item in cart:97 if item['quantity'] <= 0:98 raise ValueError(f"Invalid quantity for {item['name']}")99100 # Calculate total101 subtotal = sum(i['price'] * i['quantity'] for i in cart)102 tax = subtotal * 0.08103 total = subtotal + tax104105 # Charge payment106 charge = self.stripe.charge(user_id, total)107 if not charge['success']:108 raise RuntimeError("Payment failed")109110 # Save order111 order = {'user_id': user_id, 'total': total, 'items': cart}112 order_id = self.db.insert('orders', order)113114 # Send confirmation115 user = self.db.find('users', user_id)116 self.email.send(user['email'], f"Order {order_id} confirmed!")117118 return order_id119```120121**Output (refactored):**122```python123# cart_validator.py124class CartValidator:125 def validate(self, cart):126 if not cart:127 raise ValueError("Cart is empty")128 for item in cart:129 if item['quantity'] <= 0:130 raise ValueError(f"Invalid quantity for {item['name']}")131132# pricing.py133class PricingCalculator:134 TAX_RATE = 0.08135136 def calculate_total(self, cart):137 subtotal = sum(i['price'] * i['quantity'] for i in cart)138 return subtotal * (1 + self.TAX_RATE)139140# payment_service.py141class PaymentService:142 def __init__(self, stripe_client):143 self.stripe = stripe_client144145 def charge(self, user_id, amount):146 charge = self.stripe.charge(user_id, amount)147 if not charge['success']:148 raise RuntimeError("Payment failed")149150# order_repository.py151class OrderRepository:152 def __init__(self, db):153 self.db = db154155 def save(self, user_id, total, cart):156 return self.db.insert('orders', {'user_id': user_id, 'total': total, 'items': cart})157158# order_processor.py — now thin orchestrator159class OrderProcessor:160 def __init__(self, validator, pricing, payment, repo, notifier):161 self.validator = validator162 self.pricing = pricing163 self.payment = payment164 self.repo = repo165 self.notifier = notifier166167 def process(self, user_id, cart):168 self.validator.validate(cart)169 total = self.pricing.calculate_total(cart)170 self.payment.charge(user_id, total)171 order_id = self.repo.save(user_id, total, cart)172 self.notifier.confirm(user_id, order_id)173 return order_id174```175176Each class now has a single responsibility and can be tested in isolation.177178---179180### Example 2: Extract repeated logic and apply Guard Clauses181182**Input:**183```javascript184function getDisplayName(user) {185 if (user !== null && user !== undefined) {186 if (user.firstName !== null && user.firstName !== undefined) {187 if (user.lastName !== null && user.lastName !== undefined) {188 return user.firstName + ' ' + user.lastName;189 } else {190 return user.firstName;191 }192 } else {193 if (user.email !== null && user.email !== undefined) {194 return user.email;195 } else {196 return 'Anonymous';197 }198 }199 } else {200 return 'Anonymous';201 }202}203```204205**Output (refactored):**206```javascript207// Step 1: Apply guard clauses to flatten nesting208// Step 2: Extract predicate helper209// Step 3: Use nullish coalescing / optional chaining (ES2020+)210211function getDisplayName(user) {212 if (!user) return 'Anonymous';213 if (user.firstName && user.lastName) return `${user.firstName} ${user.lastName}`;214 if (user.firstName) return user.firstName;215 return user.email ?? 'Anonymous';216}217```218219Reduced from 20 lines to 5. Logic is identical but immediately readable.220221## Best Practices222- The Golden Rule: **never change behavior and structure in the same commit**223- Always start from a green test suite — refactoring without tests is rewriting under the illusion of safety224- Prefer small, frequent refactoring to large, infrequent rewrites225- Use your IDE's rename/extract tools instead of manual search-and-replace226- Read *Refactoring* by Martin Fowler for the canonical catalog of patterns227- When in doubt, extract a function — small, named functions are almost always better228229## Common Mistakes230- Refactoring and adding features at the same time (mixing concerns in a commit)231- Refactoring without tests — impossible to verify behavior is preserved232- Extracting too early (premature abstraction) before patterns are clear233- Renaming things inconsistently (rename in one place, miss others)234- Treating "rewrite in a cleaner way" as refactoring when the logic changes235- Gold plating — refactoring to perfection when good enough is ready to ship236237## Tips & Tricks238- Run your test suite in watch mode while refactoring so failures are instant239- `git commit --amend` or `git rebase -i` let you clean up refactoring commits before pushing240- The "rule of three": tolerate duplication once, extract on the third occurrence241- IDE shortcuts (IntelliJ `Ctrl+Alt+M`, VS Code refactor menu) are faster and safer than manual edits242- Leave code cleaner than you found it — the "boy scout rule" applied per PR243244## Related Skills245- [code-reviewer](../code-reviewer/SKILL.md)246- [test-writer](../test-writer/SKILL.md)247- [architecture-designer](../architecture-designer/SKILL.md)248- [debugger](../debugger/SKILL.md)