Refactor

---
name: refactor
description: TDD Refactor Phase - Improve code while keeping tests green using Simple Design Rules and APP mass
---

# TDD Refactor Phase

You are now in the **Refactor Phase** of TDD. Follow these instructions to improve the code while keeping tests green.

## Your Mission

Guide developers through the Refactor phase of TDD by helping them:
1. **MUST attempt at least one refactoring** - mandatory, not optional
2. Apply the Four Rules of Simple Design in priority order
3. Use Absolute Priority Premise (APP) to measure code improvements
4. Improve code quality while keeping all tests green
5. Document refactoring decisions and mass calculations
6. If no improvement is possible, explicitly document why

## Context: $ARGUMENTS

## Refactor Phase Rules
- **Mandatory refactoring attempt**: MUST try at least one improvement
- **Tests must stay green**: Never break passing tests
- **Apply Simple Design Rules**: In priority order (1 -> 2 -> 3 -> 4)
- **Calculate APP mass**: Before and after refactoring
- **Document decisions**: Explain improvements or why none were possible
- **Naming is first priority**: Evaluate if function name still fits its purpose

### Simple Design Rules (Priority Order)

#### Rule 1: Tests Pass
- **Highest priority** - never compromise working code
- All tests must pass before and after refactoring
- If tests fail, revert and try different approach

#### Rule 2: Reveals Intent
- **Second priority** - clarity trumps everything else (including APP)
- Use meaningful names for variables, functions, classes
- Structure code to be self-documenting
- Prefer explicit over clever code
- **Naming Evaluation (First Refactoring Priority)**:
  - Ask: "Does this name clearly describe what the function actually does based on all tests we have so far?"
  - Ask: "Has the function's purpose become clearer/more specific through the latest test?"
  - Rename if the name doesn't capture the current full intent
  - Especially critical when new functionality changes the nature of what the function does

#### Rule 3: No Duplication (DRY)
- **Third priority** - extract common functionality
- Look for obvious and conceptual duplication
- Knowledge should have single representation
- **Balance with Rule 2**: If DRY hurts clarity, choose clarity

#### Rule 4: Fewest Elements
- **Lowest priority** - minimize code elements
- Remove unnecessary abstractions
- Keep it simple - don't over-engineer
- Only add complexity when it serves clear purpose

### Absolute Priority Premise (APP)

#### Mass Calculation
```
Total Mass = (constants x 1) + (bindings x 1) + (invocations x 2) +
             (conditionals x 4) + (loops x 5) + (assignments x 6)
```

#### Component Values
- **Constant** (Mass: 1): Literal values (`5`, `"hello"`, `true`)
- **Binding/Scalar** (Mass: 1): Variables, parameters (`amount`, `result`)
- **Invocation** (Mass: 2): Function calls (`calculate()`, `Math.max()`)
- **Conditional** (Mass: 4): Control flow (`if`, `switch`, `?:`)
- **Loop** (Mass: 5): Iteration (`for`, `forEach`, `map`)
- **Assignment** (Mass: 6): Mutations (`x = 5`, `count++`)

#### Guidelines
- **Lower mass = Better code** (generally)
- **Rule 2 trumps APP**: Clarity over low mass
- **Use during refactoring**: Compare before/after mass
- **Context matters**: Don't sacrifice readability for mass

## Refactor Phase Process

### Step 1: Naming Evaluation (FIRST PRIORITY)
Before anything else, evaluate the naming:
```
**Naming Evaluation**:
- Current name: `calculate`
- Function purpose: "adds numbers from an array"
- Question: Does "calculate" clearly reveal this intent?
- Assessment: Too generic - "calculate" could mean anything
- Recommendation: Rename to `sumNumbers` or keep if name fits

Decision: [Rename to X] or [Keep current name because Y]
```

### Step 2: Calculate Initial APP Mass
Before making changes, calculate current code mass:
```
**Current Code Mass**:
function calculate(numbers: number[]): number {
  return numbers.reduce((sum, num) => sum + num, 0);
}

Component Count:
- Constants: 1 (literal 0) = 1
- Bindings: 3 (numbers, sum, num) = 3
- Invocations: 2 (reduce, +) = 4
- Conditionals: 0 = 0
- Loops: 1 (reduce is iteration) = 5
- Assignments: 0 = 0

Total Mass: 13
```

### Step 3: Apply Simple Design Rules (in order)
Systematically evaluate each rule:

#### Evaluate Rule 1: Tests Pass
- Are all tests currently passing?
- If not, fix before refactoring

#### Evaluate Rule 2: Reveals Intent
- Are names clear and descriptive?
- Is code structure self-documenting?
- Can intent be improved?

Potential improvements:
- Rename variables for clarity
- Extract explaining variables
- Rename functions to match purpose
- Restructure for readability

#### Evaluate Rule 3: No Duplication
- Is there duplicated code?
- Is there conceptual duplication?
- Can common logic be extracted?

Potential improvements:
- Extract helper functions
- Remove copy-paste code
- Consolidate similar logic

#### Evaluate Rule 4: Fewest Elements
- Are there unnecessary abstractions?
- Can code be simplified?
- Are all elements necessary?

Potential improvements:
- Remove unused functions/variables
- Simplify over-engineered solutions
- Inline unnecessary extractions

### Step 4: Implement Refactoring
- Make ONE improvement at a time
- Run tests after each change
- Ensure tests stay green
- If tests fail, revert change

### Step 5: Calculate New APP Mass
After refactoring, recalculate mass:
```
**Refactored Code Mass**:
[refactored code]

Component Count:
[detailed breakdown]

Total Mass: [new total]
Mass Change: [old mass] -> [new mass] (delta [difference])
```

### Step 6: Document Decision
Explain the refactoring outcome:

**If Improvements Made:**
```
**Refactoring Applied**:
- Naming: Renamed `calculate` to `sumNumbers` (better reveals intent)
- Mass: Reduced from 13 to 11 (removed conditional)
- Rule 2: Improved clarity with explaining variable

Benefits:
- Code now clearly states it sums numbers
- Reduced complexity (lower mass)
- More maintainable
```

**If No Improvements Possible:**
```
**Refactoring Evaluation**:
- Naming: `calculate` already clearly describes purpose
- Duplication: No duplicated code found
- Mass: Current implementation already minimal (mass: 13)
- Simplification: No unnecessary complexity

Reasoning:
Current implementation is already optimal because:
1. Name clearly reveals intent
2. No duplication exists
3. Mass is minimal for this functionality
4. No unnecessary abstractions

No refactoring performed - code is already clean.
```

### Step 7: Report Completion
```
Refactor Phase Complete:
**Refactoring**: [improvements made or "none possible"]
**Mass Change**: [before -> after] (if calculated)
**Tests**: All passing

Proceeding to the next test.
```

## Important Guidelines

### What to DO
- MUST attempt at least one refactoring
- Evaluate naming FIRST
- Calculate APP mass before and after
- Apply Simple Design Rules in priority order
- Keep tests green at all times
- Document all decisions
- Explain why if no improvement possible

### What NOT to do
- Never skip refactoring phase
- Never break tests during refactoring
- Never sacrifice clarity for lower mass
- Never refactor multiple things at once
- Never say "no refactoring needed" without detailed explanation

## Example Refactoring Scenarios

### Scenario 1: Naming Improvement
```typescript
// Before (mass: 13)
function calc(nums: number[]): number {
  return nums.reduce((s, n) => s + n, 0);
}

// After (mass: 13, clarity improved)
function sumNumbers(numbers: number[]): number {
  return numbers.reduce((sum, num) => sum + num, 0);
}

Refactoring:
- Naming: Renamed for clarity (Rule 2)
- Mass unchanged: 13 -> 13
- Benefit: Better reveals intent
```

### Scenario 2: Extract Helper
```typescript
// Before (mass: 22, duplication)
function differsByOneLetter(a: string, b: string): boolean {
  if (a.length !== b.length) return false;
  let diffs = 0;
  for (let i = 0; i < a.length; i++) {
    if (a[i] !== b[i]) diffs++;
  }
  return diffs === 1;
}

function isAdjacent(a: string, b: string): boolean {
  if (a.length !== b.length) return false;
  let count = 0;
  for (let i = 0; i < a.length; i++) {
    if (a[i] !== b[i]) count++;
  }
  return count === 1;
}

// After (mass: reduced, no duplication)
const countDifferences = (a: string, b: string): number => {
  if (a.length !== b.length) return Infinity;
  return a.split('').reduce((count, char, i) =>
    char !== b[i] ? count + 1 : count, 0
  );
};

const differsByOneLetter = (a: string, b: string): boolean =>
  countDifferences(a, b) === 1;

Refactoring:
- Removed duplication (Rule 3)
- Reduced mass
- Improved maintainability
```

### Scenario 3: No Refactoring Needed
```typescript
// Current code (mass: 8)
function isEmpty(str: string): boolean {
  return str.length === 0;
}

Evaluation:
- Naming: "isEmpty" clearly reveals intent
- Duplication: No duplication
- Mass: Already minimal (8)
- Simplification: No unnecessary complexity

No refactoring performed - code is already optimal.
```

## Red Flags

Watch for these violations:
- Skipping refactoring phase entirely
- Not attempting any improvements
- Breaking tests during refactoring
- Sacrificing clarity for lower mass
- Not documenting decisions

## Remember

- **Mandatory refactoring attempt** - MUST try at least one improvement
- **Naming first** - Always evaluate function names first
- **Tests stay green** - Never break passing tests
- **Simple Design Rules** - Apply in priority order (1 -> 2 -> 3 -> 4)
- **Rule 2 trumps APP** - Clarity over low mass
- **Document everything** - Mass calculations and decisions

Your goal is to systematically improve code quality using established principles, measure improvements objectively with APP, and maintain transparency through comprehensive documentation.