Refactoring

Overview

Refactoring improves code structure without changing behavior. Tests must pass before AND after.

Core principle: Behavior preservation is non-negotiable. If tests fail, you changed behavior.

Violating the letter of this process is violating the spirit of refactoring.

The Iron Law

NO REFACTORING WITHOUT TESTS PASSING FIRST AND AFTER

Refactored with failing tests? You introduced bugs. Revert immediately.

No exceptions:

• "Tests don't cover this code" → Add tests first
• "I'll run tests after all changes" → One refactoring, verify, commit
• "IDE did it automatically" → Verify tests anyway

When to Use

digraph when_refactor {
    "Want to change code?" [shape=diamond];
    "Adding/changing behavior?" [shape=diamond];
    "Tests passing?" [shape=diamond];
    "Use TDD skill" [shape=box];
    "Make tests pass first" [shape=box];
    "Apply this skill" [shape=box, style=filled, fillcolor="#ccffcc"];

    "Want to change code?" -> "Adding/changing behavior?" [label="yes"];
    "Adding/changing behavior?" -> "Use TDD skill" [label="yes"];
    "Adding/changing behavior?" -> "Tests passing?" [label="no"];
    "Tests passing?" -> "Make tests pass first" [label="no"];
    "Tests passing?" -> "Apply this skill" [label="yes"];
}

Use for: Code cleanup, technical debt, preparing for features Don't use for: Bug fixes, new features (use TDD skill)

The Safe Refactoring Loop

1. VERIFY GREEN     - Run tests, confirm all pass
2. IDENTIFY         - Pick ONE code smell (see Quick Reference table)
3. SELECT PATTERN   - Choose refactoring from refactoring-catalog.md
4. APPLY            - Make minimal structural change
5. VERIFY GREEN     - Run tests, confirm still pass
6. COMMIT           - One refactoring per commit
7. REPEAT or STOP

REQUIRED SUB-SKILL: Use superpowers:test-driven-development for test verification.

Pattern Selection: The refactoring-catalog.md file in this directory contains 24 patterns with before/after examples. Match your code smell to the pattern, review the example, then apply.

Quick Reference

See refactoring-catalog.md for complete pattern reference (29 patterns including React/Next.js).

Example: Extract Method Walkthrough

Scenario: Long function with calculation buried in display logic.

Step 1 - VERIFY GREEN:

npm test
# ✅ 47 passing

Step 2 - IDENTIFY: Long method smell - printReport() is 35 lines with embedded price calculation.

Step 3 - SELECT PATTERN: Extract Method (from catalog).

Step 4 - APPLY:

// Before: calculation embedded in printReport()
// After: extract to calculateOrderTotal()
function calculateOrderTotal(order: Order): number {
  return order.items.reduce((sum, item) =>
    sum + item.price * item.quantity, 0);
}

Step 5 - VERIFY GREEN:

npm test
# ✅ 47 passing (same count = no behavior change)

Step 6 - COMMIT:

git commit -m "refactor: extract calculateOrderTotal from printReport"

Step 7 - REPEAT: Next smell: magic number 0.08 for tax rate → Replace Magic Number with Constant.

Commit Conventions

Common Rationalizations

Red Flags - STOP

• Tests not passing before starting
• Multiple refactorings before verify
• Mixing structural and behavioral changes
• "I'll run tests at the end"
• Refactoring without understanding code
• Fixing bugs while refactoring

All of these mean: STOP. Revert. Start over.

When Stuck

Verification Checklist

Before:

• [ ] All tests pass (verified, not assumed)
• [ ] I understand what this code does
• [ ] I identified a specific code smell
• [ ] I selected a named refactoring pattern

After:

• [ ] All tests still pass
• [ ] Behavior unchanged (verified)
• [ ] One commit per refactoring
• [ ] Commit message follows convention

Technical Debt Prioritization

Severity:

• Critical: Blocks development, causes bugs
• High: Slows development, increases risk
• Medium: Code smell, future concern
• Low: Cosmetic, nice to have

Priority = (Velocity Impact x Bug Risk) / Effort

Example: Scale 1-5 for each factor:

Address Critical first, then High during feature work.