refactor-guide

name	refactor-guide
description	Refactor safely — keep tests green, change structure without behavior change, no public API breakage. Use for code maintenance.
origin	FlowDeck

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) { ... }

Danger Signs — Stop Immediately

• Tests breaking during refactor → undo, try smaller step
• Adding a feature while refactoring → separate commit
• Renaming AND moving in same commit → split into two commits
• Touching unrelated code → leave it alone

Output Format

## Refactor Summary

### Transformations (in order applied)
1. Extracted `validateOrderItems()` — order.ts:23-28
2. Extracted `calculateOrderTotal()` — order.ts:29-31
3. Renamed `getData()` → `fetchUserProfile()` — 4 files

### Before/After
- order.ts: 180 lines → 120 lines
- 2 new unit tests for extracted functions

### Test Results
- Before: 45 tests passing
- After: 47 tests passing