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

// 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

// 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

// 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.