refactor-guide

Refactor Guide Skill

Changes structure without changing behavior. One transformation at a time. Tests must stay green throughout.

When to Activate

Activate when:

• A function is over 50 lines
• A file is over 800 lines
• There is significant code duplication
• Variable or function names are misleading
• You are preparing code for a new feature

Core Principles

• Tests green before you start — if not, fix tests first
• One transformation per commit
• No features in refactor commits
• If any test breaks, undo and try a smaller step

Safe Refactoring Process

1. npm test → must be GREEN before starting

2. Apply ONE transformation
   (extract function, rename, move module — one thing only)

3. npm test → must still be GREEN

4. git commit -m "refactor: [description]"

5. Repeat from step 2

Extract Function Pattern

// ❌ Before — inline, hard to test independently
function createOrder(items: Item[], userId: string) {
  if (!items || items.length === 0) {
    throw new Error('Order must have items');
  }
  const total = items.reduce((s, i) => s + i.price * i.qty, 0);
  if (total > 10000) {
    throw new Error('Order total exceeds limit');
  }
  // ... save to DB
}

// ✅ After — each function has a single responsibility
function validateOrderItems(items: Item[]): void {
  if (!items || items.length === 0) {
    throw new Error('Order must have items');
  }
}

function calculateOrderTotal(items: Item[]): number {
  return items.reduce((s, i) => s + i.price * i.qty, 0);
}

function assertTotalWithinLimit(total: number): void {
  if (total > 10000) throw new Error('Order total exceeds limit');
}

function createOrder(items: Item[], userId: string) {
  validateOrderItems(items);
  const total = calculateOrderTotal(items);
  assertTotalWithinLimit(total);
  // ... save to DB
}

Extract Variable Pattern

// ❌ Before — magic numbers and complex expression
if (user.createdAt < Date.now() - 30 * 24 * 60 * 60 * 1000) { ... }

// ✅ After — named intent
const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
const accountAge = Date.now() - user.createdAt;
const isNewUser = accountAge < THIRTY_DAYS_MS;
if (isNewUser) { ... }