From core
Refactors code to improve structure, readability, and maintainability while preserving behavior. Guides test-driven cycle, checklists, and patterns like extract function.
npx claudepluginhub thebushidocollective/han --plugin coreThis skill is limited to using the following tools:
Improve code structure and quality while preserving behavior.
Refactors code structure for better readability and maintainability without changing behavior. Applies patterns like extract/inline/rename functions, eliminates duplication, addresses code smells like long functions and deep nesting.
Surgical refactoring improves code maintainability without behavior changes: extracts functions, renames variables, breaks god functions, boosts type safety, removes smells.
Surgical refactoring improves maintainability without changing behavior: extracts functions, renames variables, breaks god functions, boosts type safety, fixes code smells, applies patterns. For gradual cleanups of hard-to-maintain code.
Share bugs, ideas, or general feedback.
Improve code structure and quality while preserving behavior.
han-core:refactor - Restructure code to improve quality without changing behavior
/refactor [arguments]
Tests are your safety net. Never refactor without tests.
Each step must be reversible. If tests fail, revert and try smaller change.
STOP if any of these are false:
If no tests exist:
Readability issues:
Maintainability issues:
Complexity issues:
Problem: Function does too many things
// Before: Long function doing multiple things
function processOrder(order: Order) {
// Validate order
if (!order.items || order.items.length === 0) {
throw new Error('Empty order')
}
if (!order.customer || !order.customer.email) {
throw new Error('Invalid customer')
}
// Calculate totals
let subtotal = 0
for (const item of order.items) {
subtotal += item.price * item.quantity
}
const tax = subtotal * 0.08
const shipping = subtotal > 50 ? 0 : 9.99
const total = subtotal + tax + shipping
// Save to database
return database.save({
...order,
subtotal,
tax,
shipping,
total
})
}
// After: Extracted into focused functions
function processOrder(order: Order) {
validateOrder(order)
const totals = calculateTotals(order)
return saveOrder(order, totals)
}
function validateOrder(order: Order): void {
if (!order.items || order.items.length === 0) {
throw new Error('Empty order')
}
if (!order.customer || !order.customer.email) {
throw new Error('Invalid customer')
}
}
function calculateTotals(order: Order) {
const subtotal = order.items.reduce(
(sum, item) => sum + item.price * item.quantity,
0
)
const tax = subtotal * 0.08
const shipping = subtotal > 50 ? 0 : 9.99
const total = subtotal + tax + shipping
return { subtotal, tax, shipping, total }
}
function saveOrder(order: Order, totals: Totals) {
return database.save({ ...order, ...totals })
}
Benefits: Each function has single responsibility, easier to test, easier to understand
Problem: Complex expression that's hard to understand
// Before: Dense, hard to parse
if (user.age >= 18 && user.country === 'US' && !user.banned && user.verified) {
// ...
}
// After: Intent is clear
const isAdult = user.age >= 18
const isUSResident = user.country === 'US'
const hasGoodStanding = !user.banned && user.verified
const canPurchase = isAdult && isUSResident && hasGoodStanding
if (canPurchase) {
// ...
}
Benefits: Self-documenting, easier to debug, easier to modify
Problem: Unnecessary indirection that doesn't add clarity
// Before: Over-abstraction
function getTotal(order: Order) {
return calculateTotalAmount(order)
}
function calculateTotalAmount(order: Order) {
return order.subtotal + order.tax
}
// After: Inline the unnecessary layer
function getTotal(order: Order) {
return order.subtotal + order.tax
}
When to inline: Abstraction doesn't add value, makes code harder to follow
Problem: Unclear or misleading names
// Before: Unclear
function proc(d: any) {
const r = d.x * d.y
return r
}
// After: Self-explanatory
function calculateArea(dimensions: Dimensions) {
const area = dimensions.width * dimensions.height
return area
}
Benefits: Code is self-documenting, no need to guess what variables mean
Problem: Unexplained numbers in code
// Before: What's 0.08? What's 9.99?
const tax = subtotal * 0.08
const shipping = subtotal > 50 ? 0 : 9.99
// After: Clear meaning
const TAX_RATE = 0.08
const FREE_SHIPPING_THRESHOLD = 50
const STANDARD_SHIPPING_COST = 9.99
const tax = subtotal * TAX_RATE
const shipping = subtotal > FREE_SHIPPING_THRESHOLD ? 0 : STANDARD_SHIPPING_COST
Problem: Same code in multiple places
// Before: Duplication
function formatUserName(user: User) {
return `${user.firstName} ${user.lastName}`.trim()
}
function formatAdminName(admin: Admin) {
return `${admin.firstName} ${admin.lastName}`.trim()
}
function formatAuthorName(author: Author) {
return `${author.firstName} ${author.lastName}`.trim()
}
// After: One implementation
function formatFullName(person: { firstName: string; lastName: string }) {
return `${person.firstName} ${person.lastName}`.trim()
}
// Usage
formatFullName(user)
formatFullName(admin)
formatFullName(author)
Problem: Complex nested if/else
// Before: Nested conditionals
function getShippingCost(order: Order) {
if (order.total > 100) {
return 0
} else {
if (order.items.length > 5) {
return 5.99
} else {
if (order.weight > 10) {
return 15.99
} else {
return 9.99
}
}
}
}
// After: Early returns, flat structure
function getShippingCost(order: Order) {
if (order.total > 100) return 0
if (order.items.length > 5) return 5.99
if (order.weight > 10) return 15.99
return 9.99
}
// Or: Look-up table
const SHIPPING_RULES = [
{ condition: (o: Order) => o.total > 100, cost: 0 },
{ condition: (o: Order) => o.items.length > 5, cost: 5.99 },
{ condition: (o: Order) => o.weight > 10, cost: 15.99 },
]
function getShippingCost(order: Order) {
const rule = SHIPPING_RULES.find(r => r.condition(order))
return rule?.cost ?? 9.99
}
Problem: Type checks scattered throughout code
// Before: Type checking everywhere
function calculatePrice(item: Item) {
if (item.type === 'book') {
return item.basePrice * 0.9 // 10% discount
} else if (item.type === 'electronics') {
return item.basePrice * 1.15 // 15% markup
} else if (item.type === 'clothing') {
return item.basePrice
}
}
// After: Polymorphism
interface Item {
calculatePrice(): number
}
class Book implements Item {
calculatePrice() {
return this.basePrice * 0.9
}
}
class Electronics implements Item {
calculatePrice() {
return this.basePrice * 1.15
}
}
class Clothing implements Item {
calculatePrice() {
return this.basePrice
}
}
// Usage: No type checking needed
const price = item.calculatePrice()
Problem: Function tries to do too many things
// Before: Does validation, calculation, and saving
function processPayment(payment: Payment) {
// Validation
if (!payment.amount || payment.amount <= 0) {
throw new Error('Invalid amount')
}
if (!payment.method) {
throw new Error('Payment method required')
}
// Calculation
const fee = payment.amount * 0.029 + 0.30
const total = payment.amount + fee
// Persistence
const record = database.save({
amount: payment.amount,
fee,
total,
method: payment.method,
timestamp: Date.now()
})
// Notification
notificationService.send({
user: payment.user,
message: `Payment of $${total} processed`
})
return record
}
// After: Separate concerns
function processPayment(payment: Payment) {
validatePayment(payment)
const totals = calculatePaymentTotals(payment)
const record = savePayment(payment, totals)
notifyPaymentProcessed(payment.user, totals.total)
return record
}
Safety first:
# 1. Ensure tests pass
npm test
# All tests passing
# 2. Make ONE refactoring change
# Example: Extract function
# 3. Run tests immediately
npm test
# Still passing
# 4. Commit with descriptive message
git add .
git commit -m "refactor: extract validateOrder function"
# 5. Repeat for next refactoring
# Make another small change, test, commit
# Tests failed after refactoring
# Option 1: Revert and try smaller change
git reset --hard HEAD
# Make smaller, safer change
# Option 2: Debug and fix
# Find what broke
# Fix it
# Run tests again
"Leave code better than you found it"
When touching code for any reason:
Small improvements accumulate
Before adding feature, refactor to make it easy
1. Need to add feature
2. Current code structure makes it hard
3. Refactor first to make space
4. Then add feature in clean code
Quote: "Make the change easy, then make the easy change"
Fix things you notice while working
Dedicated time to improve code health
Before every change:
After every change:
If tests fail:
Risk: Change behavior without noticing
Solution: Add tests first, then refactor
Risk: Hard to debug if something breaks
Solution: One refactoring at a time, commit frequently
Risk: It's not refactoring if behavior changes
Solution: Tests must still pass, functionality unchanged
Risk: More complex after "refactoring"
Solution: Simpler is better, don't add unnecessary abstraction
Risk: Mistakes due to rushing
Solution: Defer to when you have time to do it right
Good refactoring results in:
If any test fails, it wasn't successful refactoring
After refactoring:
## Refactoring: [Brief description]
### Before
[Description of code smell or issue]
### Changes Made
- [Change 1 with reasoning]
- [Change 2 with reasoning]
- [Change 3 with reasoning]
### After
[How the code is better now]
### Verification
[Evidence that behavior unchanged - use proof-of-work skill]
- All tests pass: [test output]
- No functionality changed
- Code is more [readable/maintainable/simple]
When the user says:
Automated refactoring tools:
Manual refactoring:
Refactoring is about improving structure without changing what the code does.