Test-Driven Development (TDD) Workflow

Overview

When to Use

• New features
• Bug fixes
• Refactoring
• Behavior changes

• Throwaway prototypes
• Generated code
• Configuration files

Session-Management Integration

--tdd

• Automatic RED-GREEN-REFACTOR checkpoint tracking
• Test coverage metrics in session report
• TDD cycle enforcement (blocks skipping steps)
• Session handoff includes test statistics

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Red-Green-Refactor

RED → Verify RED → GREEN → Verify GREEN → REFACTOR → Repeat

RED - Write Failing Test

test('retries failed operations 3 times', async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error('fail');
    return 'success';
  };

  const result = await retryOperation(operation);

  expect(result).toBe('success');
  expect(attempts).toBe(3);
});

test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
});

• One behavior
• Clear name
• Real code (no mocks unless unavoidable)

Verify RED - Watch It Fail

npm test path/to/test.test.ts

• Test fails (not errors)
• Failure message is expected
• Fails because feature missing (not typos)

GREEN - Minimal Code

async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error('unreachable');
}

async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: 'linear' | 'exponential';
    onRetry?: (attempt: number) => void;
  }
): Promise<T> {
  // YAGNI - You Aren't Gonna Need It
}

Verify GREEN - Watch It Pass

npm test path/to/test.test.ts

• Test passes
• Other tests still pass
• Output pristine (no errors, warnings)

REFACTOR - Clean Up

• Remove duplication
• Improve names
• Extract helpers

Repeat

Session-Management Commands

Start TDD Session

# Explicit TDD session
python scripts/session.py start feature/auth --objective "Add auth (TDD)"

# Or with TDD flag
python scripts/session.py start feature/auth --tdd

• Automatic checkpoint prompts
• Cycle tracking
• Test coverage monitoring
• Enforced verification steps

TDD Checkpoints

# RED checkpoint (test written, verified failing)
python scripts/session.py checkpoint --label "red-user-validation" --tdd-phase RED

# GREEN checkpoint (minimal code, test passing)
python scripts/session.py checkpoint --label "green-user-validation" --tdd-phase GREEN

# REFACTOR checkpoint (optional, when refactoring)
python scripts/session.py checkpoint --label "refactor-extract-validator" --tdd-phase REFACTOR

View TDD Metrics

# Session summary with TDD stats
python scripts/session.py status

# Shows:
# - RED-GREEN-REFACTOR cycles completed
# - Tests written vs passing
# - Average cycle time
# - Coverage trend

End TDD Session

python scripts/session.py end --handoff

• Total TDD cycles completed
• Test files created
• Coverage metrics
• Discipline adherence (skipped verifications flagged)

Good Tests

test('validates email and domain and whitespace')

test('test1')

Why Order Matters

• Might test wrong thing
• Might test implementation, not behavior
• Might miss edge cases you forgot
• You never saw it catch the bug

• No record of what you tested
• Can't re-run when code changes
• Easy to forget cases under pressure
• "It worked when I tried it" ≠ comprehensive

• Delete and rewrite with TDD (X more hours, high confidence)
• Keep it and add tests after (30 min, low confidence, likely bugs)

• Finds bugs before commit (faster than debugging after)
• Prevents regressions (tests catch breaks immediately)
• Documents behavior (tests show how to use code)
• Enables refactoring (change freely, tests catch breaks)

Common Rationalizations

Red Flags - STOP and Start Over

• Code before test
• Test after implementation
• Test passes immediately
• Can't explain why test failed
• Tests added "later"
• Rationalizing "just this once"
• "I already manually tested it"
• "Tests after achieve the same purpose"
• "It's about spirit not ritual"
• "Keep as reference" or "adapt existing code"
• "Already spent X hours, deleting is wasteful"
• "TDD is dogmatic, I'm being pragmatic"
• "This is different because..."

Example: Bug Fix

test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

$ npm test
FAIL: expected 'Email required', got undefined

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

$ npm test
PASS

Verification Checklist

• Every new function/method has a test
• Watched each test fail before implementing
• Each test failed for expected reason (feature missing, not typo)
• Wrote minimal code to pass each test
• All tests pass
• Output pristine (no errors, warnings)
• Tests use real code (mocks only if unavoidable)
• Edge cases and errors covered

When Stuck

Debugging Integration

Final Rule

Production code → test exists and failed first
Otherwise → not TDD

CCMP Plugin Integration

.ccmp/state.json

Integration Detection (Modern API)

from lib.ccmp_integration import is_session_active, is_tdd_mode

if is_session_active():
    # Enhanced TDD mode with session integration
    pass

1. .git/sessions/<branch>/

   directory exists
2. Session config has TDD objective or

   --tdd

   flag

3. session.py

   commands available

With session-management 🔄

python scripts/session.py start feature/auth --tdd
# → TDD workflow detects via integration API
# → Enhanced mode activates automatically

• Cycles completed tracked in session state
• Session status shows TDD discipline score
• Handoffs include test coverage metrics

With claude-context-manager 📚

• Can trigger

  tests/*/claude.md

  updates
• Documents discovered test patterns
• Keeps test strategy current

from lib.ccmp_integration import CCMPIntegration

integration = CCMPIntegration()
integration.update_state("tdd-workflow", {
    "active": True,
    "cycles_today": 5,
    "current_phase": "GREEN",
    "discipline_score": 100
})

Integration Benefits

• 📊 Track RED-GREEN-REFACTOR cycles in session metrics
• 📍 Automatic checkpoints at each TDD phase
• 📈 Test coverage trends across session
• 🎯 TDD discipline enforcement (harder to skip steps)
• 📝 Rich handoff documents with test statistics
• ⏱️ Cycle time tracking and optimization insights

• ✅ Full TDD guidance and discipline
• ✅ All core principles and workflows
• ✅ Verification checklists
• ✅ Common rationalization detection