Recursive TDD

recursive-tdd

Overview

Test-Driven Development is mandatory for all recursive-mode implementation work. This skill ensures test-first discipline is followed rigorously and recorded in a way recursive-mode tooling can verify.

Core Principle: If you didn't watch the test fail, you don't know if it tests the right thing.

The Iron Law for recursive-mode:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Trigger examples

• Implement Phase 3 for run '<run-id>'
• Add a failing regression test first, then fix the bug
• I already wrote the code; now add tests (should trigger TDD reset guidance)
• Follow RED-GREEN-REFACTOR for this change

When to Use

Always in Phase 3 (Implementation):

• New features
• Bug fixes
• Refactoring
• Behavior changes

Default rule:

• Not for "simple" changes
• Not when "under pressure"
• Not because "tests after achieve same goals"

Explicit exception path only:

• If strict RED-first flow is genuinely infeasible, declare TDD Mode: pragmatic in the Phase 3 artifact
• Record a concrete exception reason
• Record compensating validation evidence under /.recursive/run/<run-id>/evidence/
• Treat this as an explicit deviation, not a silent shortcut

RED-GREEN-REFACTOR Cycle

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    record [label="Record in\nPhase 3 artifact", shape=box];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> record;
}

RED - Write Failing Test

Write one minimal test showing what should happen.

Requirements:

• One behavior per test
• Clear, descriptive name
• Test real code (no mocks unless unavoidable)
• Clear assertion showing expected outcome

<Good>
```typescript
test('rejects empty email with clear error message', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email is required');
});
```
</Good>

<Bad>
```typescript
test('email validation works', async () => {
  const mock = jest.fn().mockResolvedValue({ valid: true });
  const result = await validateEmail(mock);
  expect(mock).toHaveBeenCalled();
});
```
</Bad>

Verify RED - Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts

Confirm:

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

Record in Phase 3 artifact:

### TDD Cycle for R3 (Email Validation)

TDD Mode: strict

RED Evidence:
- `/.recursive/run/<run-id>/evidence/logs/red/<file>.log`

GREEN Evidence:
- `/.recursive/run/<run-id>/evidence/logs/green/<file>.log`

**RED Phase:**
- Test: `rejects empty email with clear error message`
- Command: `npm test src/forms/email.test.ts`
- Expected failure: "Email is required" not found
- Actual failure: [paste output]
- RED verified: PASS

GREEN - Minimal Code

Write simplest code to pass the test.

Rules:

• Just enough to pass
• No additional features
• No "while I'm here" improvements
• No refactoring yet

<Good>
```typescript
function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email is required' };
  }
  // ... rest of form handling
}
```
</Good>

<Bad>
```typescript
function submitForm(
  data: FormData,
  options?: {
    strictMode?: boolean;
    customValidators?: Validator[];
    onValidationError?: (err: Error) => void;
  }
) {
  // YAGNI - over-engineered
}
```
</Bad>

Record in Phase 3 artifact:

**GREEN Phase:**
- Implementation: Added null check for email field
- Command: `npm test src/forms/email.test.ts`
- Result: PASS
- GREEN verified: PASS

REFACTOR - Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers
• Keep tests green

Never add behavior during refactor.

Record in Phase 3 artifact:

**REFACTOR Phase:**
- Extracted `validateRequired(field, name)` helper
- Renamed `submitForm` to `processFormSubmission` for clarity
- All tests still passing: PASS

Common Process Shortcuts (STOP)