name: refactor
description: "Improve existing code without changing its external behavior. Identifies code smells, applies proven refactoring patterns, and ensures safety through tests. Makes code more readable, maintainable, and performant while preserving functionality."
phase: REVIEW
category: core
version: "1.0.0"
depends_on: [implement]
tags: [quality, refactoring, improvement, code-quality]

Refactor

Improve code without changing behavior.

When to Use

• Before adding features — Clean up code that will be modified
• After code review — Address feedback about code quality
• Technical debt — Pay down accumulated cruft
• Performance issues — Optimize hot paths
• Comprehension problems — Make code easier to understand
• When you say: "refactor this", "clean up", "improve this code"

Reference Requirements

MUST read before applying this skill:

Read if applicable:

Verification: Ensure tests pass after refactoring to confirm behavior preserved.

Required Deliverables

Core Concept

Refactor answers: "How do I make this code better without breaking it?"

Refactoring is:
- Behavior-preserving — External behavior stays the same
- Incremental — Small steps, each leaving code working
- Test-supported — Tests verify nothing broke
- Intentional — Driven by specific improvements

Refactoring is NOT:
- Adding new features
- Fixing bugs (that changes behavior)
- Rewriting from scratch
- Performance optimization alone (though it can enable it)

The Refactoring Process

┌─────────────────────────────────────────────────────────┐
│                  REFACTORING PROCESS                    │
│                                                         │
│  1. ENSURE TEST COVERAGE                                │
│     └─→ Can't refactor safely without tests             │
│                                                         │
│  2. IDENTIFY CODE SMELLS                                │
│     └─→ What specifically is wrong?                     │
│                                                         │
│  3. SELECT REFACTORING                                  │
│     └─→ Which pattern addresses the smell?              │
│                                                         │
│  4. APPLY IN SMALL STEPS                                │
│     └─→ One change at a time, tests passing             │
│                                                         │
│  5. TEST AFTER EACH STEP                                │
│     └─→ Run tests, verify behavior unchanged            │
│                                                         │
│  6. COMMIT FREQUENTLY                                   │
│     └─→ Small commits, easy to revert                   │
│                                                         │
│  7. REVIEW THE RESULT                                   │
│     └─→ Is the code actually better?                    │
└─────────────────────────────────────────────────────────┘

Step 1: Ensure Test Coverage

Never refactor without tests.

Before refactoring, verify:

## Pre-Refactoring Checklist

- [ ] Unit tests exist for the code being changed
- [ ] Tests cover the main behaviors
- [ ] Tests cover important edge cases
- [ ] All tests pass
- [ ] You understand what the tests are checking

If tests don't exist:

## Adding Tests Before Refactoring

1. Write characterization tests (tests that capture current behavior)
2. Focus on inputs and outputs, not implementation
3. Cover happy path and error cases
4. Get tests passing before any refactoring

// Characterization test - captures current behavior
describe('OrderCalculator', () => {
  it('calculates total for current production data', () => {
    // Use actual examples from production
    const order = {
      items: [
        { price: 1999, quantity: 2 },
        { price: 499, quantity: 1 },
      ],
      discount: 0.1,
    };

    // Capture current output (run once to get value)
    expect(calculator.getTotal(order)).toBe(4047);
  });
});

Step 2: Identify Code Smells

Code smells are symptoms that suggest refactoring opportunities.

Bloaters (Too Big)

Object-Orientation Abusers

Change Preventers

Dispensables (Remove)

Couplers (Too Connected)

→ See references/code-smells.md

Step 3: Select Refactoring

Match the smell to the refactoring:

┌─────────────────────────────────────────────────────────┐
│             SMELL → REFACTORING DECISION                │
│                                                         │
│  Long Method?                                           │
│  └─→ Extract Method                                     │
│                                                         │
│  Duplicate Code?                                        │
│  ├─→ Same class: Extract Method                         │
│  ├─→ Sibling classes: Pull Up Method                    │
│  └─→ Unrelated classes: Extract Class                   │
│                                                         │
│  Long Parameter List?                                   │
│  ├─→ Related params: Introduce Parameter Object         │
│  └─→ Can compute: Replace Parameter with Method Call    │
│                                                         │
│  Switch on Type?                                        │
│  └─→ Replace Conditional with Polymorphism              │
│                                                         │
│  Feature Envy?                                          │
│  └─→ Move Method to the class it envies                 │
│                                                         │
│  Data Clump?                                            │
│  └─→ Extract Class for the clumped data                 │
│                                                         │
│  Primitive Obsession?                                   │
│  └─→ Replace Primitive with Value Object                │
│                                                         │
└─────────────────────────────────────────────────────────┘

Step 4: Apply in Small Steps

The key to safe refactoring: small, reversible steps.

Extract Method Example

Before:

function printOrder(order: Order): void {
  console.log('Order Details');
  console.log('=============');

  // Print items
  let total = 0;
  for (const item of order.items) {
    console.log(`${item.name}: $${item.price}`);
    total += item.price * item.quantity;
  }

  // Apply discount
  if (order.discount > 0) {
    const discountAmount = total * order.discount;
    total -= discountAmount;
    console.log(`Discount: -$${discountAmount}`);
  }

  // Print total
  console.log('=============');
  console.log(`Total: $${total}`);
}

Step 1 - Extract printItems:

function printOrder(order: Order): void {
  console.log('Order Details');
  console.log('=============');

  const subtotal = printItems(order.items);  // ← Extracted

  // Apply discount
  let total = subtotal;
  if (order.discount > 0) {
    const discountAmount = total * order.discount;
    total -= discountAmount;
    console.log(`Discount: -$${discountAmount}`);
  }

  console.log('=============');
  console.log(`Total: $${total}`);
}

function printItems(items: OrderItem[]): number {
  let total = 0;
  for (const item of items) {
    console.log(`${item.name}: $${item.price}`);
    total += item.price * item.quantity;
  }
  return total;
}

Run tests. ✓

Step 2 - Extract applyDiscount:

function printOrder(order: Order): void {
  console.log('Order Details');
  console.log('=============');

  const subtotal = printItems(order.items);
  const total = applyDiscount(subtotal, order.discount);  // ← Extracted

  console.log('=============');
  console.log(`Total: $${total}`);
}

function applyDiscount(subtotal: number, discount: number): number {
  if (discount > 0) {
    const discountAmount = subtotal * discount;
    console.log(`Discount: -$${discountAmount}`);
    return subtotal - discountAmount;
  }
  return subtotal;
}

Run tests. ✓

Step 3 - Extract printHeader and printTotal:

function printOrder(order: Order): void {
  printHeader();
  const subtotal = printItems(order.items);
  const total = applyDiscount(subtotal, order.discount);
  printTotal(total);
}

function printHeader(): void {
  console.log('Order Details');
  console.log('=============');
}

function printTotal(total: number): void {
  console.log('=============');
  console.log(`Total: $${total}`);
}

Run tests. ✓ Commit.

→ See references/refactoring-catalog.md

Step 5: Test After Each Step

// After EVERY small change:
npm test

// If tests fail:
// 1. Undo the change (git checkout)
// 2. Try smaller step
// 3. Or fix the issue before continuing

Testing Strategies During Refactoring

Step 6: Commit Frequently

# Good: Small, atomic commits
git commit -m "refactor: extract printItems method"
git commit -m "refactor: extract applyDiscount method"
git commit -m "refactor: extract header and footer printing"

# Bad: One big commit
git commit -m "refactor: cleaned up printOrder"

Benefits:
- Easy to revert one step if something breaks
- Clear history of what changed
- Easier code review
- Can bisect to find problems

Step 7: Review the Result

After refactoring, ask:

## Post-Refactoring Review

### Readability
- [ ] Is the code easier to understand?
- [ ] Are names clearer?
- [ ] Is the structure more logical?

### Maintainability
- [ ] Is it easier to change?
- [ ] Are responsibilities clear?
- [ ] Is duplication reduced?

### Correctness
- [ ] All tests still pass?
- [ ] No behavior changed?
- [ ] Edge cases still work?

### Did we overdo it?
- [ ] Is it simpler, not more complex?
- [ ] Did we avoid premature abstraction?
- [ ] Is it still easy to debug?

Common Refactorings

Extract Method

When: Long method, code block that can be named

// Before
function processOrder(order: Order): void {
  // Validate order
  if (!order.items.length) throw new Error('Empty order');
  if (!order.customer) throw new Error('No customer');
  if (order.total < 0) throw new Error('Invalid total');

  // Process...
}

// After
function processOrder(order: Order): void {
  validateOrder(order);
  // Process...
}

function validateOrder(order: Order): void {
  if (!order.items.length) throw new Error('Empty order');
  if (!order.customer) throw new Error('No customer');
  if (order.total < 0) throw new Error('Invalid total');
}

Rename

When: Name doesn't clearly express intent

// Before
function calc(d: number[]): number {
  let t = 0;
  for (const n of d) t += n;
  return t / d.length;
}

// After
function calculateAverage(numbers: number[]): number {
  let sum = 0;
  for (const number of numbers) sum += number;
  return sum / numbers.length;
}

Replace Conditional with Polymorphism

When: Switch statement on type that appears in multiple places

// Before
function calculatePay(employee: Employee): number {
  switch (employee.type) {
    case 'hourly':
      return employee.hours * employee.rate;
    case 'salaried':
      return employee.salary / 12;
    case 'commission':
      return employee.sales * employee.commissionRate;
  }
}

// After
interface Employee {
  calculatePay(): number;
}

class HourlyEmployee implements Employee {
  constructor(private hours: number, private rate: number) {}
  calculatePay(): number {
    return this.hours * this.rate;
  }
}

class SalariedEmployee implements Employee {
  constructor(private salary: number) {}
  calculatePay(): number {
    return this.salary / 12;
  }
}

class CommissionEmployee implements Employee {
  constructor(private sales: number, private rate: number) {}
  calculatePay(): number {
    return this.sales * this.rate;
  }
}

Introduce Parameter Object

When: Same parameters passed together repeatedly

// Before
function createEvent(
  startDate: Date,
  endDate: Date,
  startTime: string,
  endTime: string,
  timezone: string
): Event { }

function validateDateRange(
  startDate: Date,
  endDate: Date,
  startTime: string,
  endTime: string,
  timezone: string
): boolean { }

// After
interface DateRange {
  startDate: Date;
  endDate: Date;
  startTime: string;
  endTime: string;
  timezone: string;
}

function createEvent(range: DateRange): Event { }
function validateDateRange(range: DateRange): boolean { }

Replace Primitive with Value Object

When: Primitive carries domain meaning

// Before
function processPayment(amountCents: number, currency: string): void {
  // Easy to make mistakes:
  // - Pass dollars instead of cents
  // - Pass invalid currency
  // - Mix up currencies
}

// After
class Money {
  constructor(
    private readonly cents: number,
    private readonly currency: Currency
  ) {
    if (cents < 0) throw new Error('Amount cannot be negative');
  }

  add(other: Money): Money {
    if (this.currency !== other.currency) {
      throw new Error('Currency mismatch');
    }
    return new Money(this.cents + other.cents, this.currency);
  }

  toString(): string {
    return `${this.currency} ${(this.cents / 100).toFixed(2)}`;
  }
}

function processPayment(amount: Money): void {
  // Type system prevents mistakes
}

→ See references/refactoring-catalog.md

When NOT to Refactor

Refactoring vs Rewriting

Rule of thumb: If you can improve the code through a series of small, safe changes, refactor. If the code is fundamentally broken or the design is wrong, consider rewriting.

Relationship to Other Skills

Key Principles

Small steps. Each change should be trivial and safe.

Tests first. Never refactor without tests.

One thing at a time. Don't mix refactoring with feature work.

Commit often. Make it easy to revert.

Know when to stop. Good enough is good enough.

Preserve behavior. The whole point is not changing what the code does.

Mode-Specific Behavior

Refactoring scope and constraints differ by orchestrator mode:

Greenfield Mode

Brownfield-Polish Mode

Polish considerations:
- Refactor only what you're changing
- Don't "improve" unrelated code
- Match refactoring style to codebase
- Document why refactoring was needed
- Get approval for large refactors

Brownfield-Enterprise Mode

Enterprise refactoring constraints:
- Refactoring requires separate change request
- No refactoring mixed with feature changes
- Must justify business value of refactoring
- Full test coverage required before and after
- Rollback plan required

Enterprise refactoring process:
1. Create separate CR for refactoring
2. Get CR approved
3. Implement refactoring in isolation
4. Full regression testing
5. Merge refactoring first
6. Then implement feature change

References

• references/code-smells.md: Detailed catalog of code smells
• references/refactoring-catalog.md: Complete refactoring patterns
• references/refactoring-strategies.md: Large-scale refactoring approaches
• references/legacy-code-patterns.md: Working with code without tests