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

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

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)

Red Flags - STOP and Start Over

If you encounter any of these, DELETE CODE and restart with TDD:

• Code written before test
• Test passes immediately (not testing what you think)
• "I'll add tests later"
• "This is too simple to test"
• "I know what I'm doing, I don't need the ritual"
• Can't explain why test failed (or didn't fail)
• Test testing mock behavior, not real behavior
• Multiple behaviors in one test ("and" in test name)

Integration with recursive-mode Phase 3

Routing Awareness

If TDD execution uses delegated review, test audit, or bounded routed implementation help, re-read:

• /.recursive/config/recursive-router.json
• /.recursive/config/recursive-router-discovered.json

immediately before choosing the delegated CLI/model, and use the routed policy or explicit fallback rather than ad hoc model selection.

Phase 3 Artifact TDD Section

Every Phase 3 artifact must include:

## TODO

- [ ] Replace every placeholder with concrete TDD evidence for the current implementation phase.

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Subagent Capability Probe: [what proved availability or unavailability]
Delegation Decision Basis: [why self-audit or delegation was chosen]

## TDD Compliance Log

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`

### Requirement R1 (Feature X)

**Test:** `test/features/x.test.ts` - "should do Y when Z"
- RED: [timestamp] - Failed as expected: [output]
- GREEN: [timestamp] - Minimal implementation: [description]
- REFACTOR: [timestamp] - Cleanups: [description]
- Final state: PASS - all tests passing

### Requirement R2 (Bug Fix)

**Regression Test:** `test/bugs/issue-123.test.ts` - "reproduces crash on empty input"
- RED: [timestamp] - Confirmed bug: [output]
- GREEN: [timestamp] - Fix applied: [description]
- REFACTOR: [timestamp] - N/A (minimal fix)
- Final state: PASS - test passes, bug fixed

## Requirement Completion Status

- `R1` | `implemented` | Changed Files: `path/to/file`
- `R1` | `verified` | Evidence: `/.recursive/run/<run-id>/evidence/logs/green/<file>.log`

If strict mode cannot be followed, the artifact must include:

## Pragmatic TDD Exception

Exception reason: [specific reason strict RED-first flow was not feasible]
Compensating validation:
- [extra tests, targeted manual verification, diff review, etc.]
- `/.recursive/run/<run-id>/evidence/<supporting-file>`

Phase 3 Coverage Gate Addition

## Coverage Gate

- [ ] Every new function has a corresponding test
- [ ] Every bug fix has a regression test that fails before fix
- [ ] All RED phases documented with failure output
- [ ] All GREEN phases documented with minimal implementation
- [ ] All tests passing (no skipped tests)
- [ ] No production code written before failing test

TDD Compliance: PASS / FAIL

Phase 3 Approval Gate Addition

## Approval Gate

- [ ] TDD Compliance: PASS
- [ ] Implementation matches Phase 3 plan
- [ ] No code without preceding failing test
- [ ] All tests documented in TDD Compliance Log

Approval: PASS / FAIL

Bug Fix TDD Procedure

1. Add Regression Test First

   • Write test that reproduces the bug
   • Run test, confirm it fails with expected error
   • Document failure in Phase 3 artifact

2. Implement Minimal Fix

   • Fix only what's needed to make test pass
   • Run test, confirm it passes
   • Document fix in Phase 3 artifact

3. Verify No Regressions

   • Run full test suite
   • Confirm nothing else broke
   • Document in Phase 3 artifact

4. Lock Phase 3

   • TDD Mode is declared
   • TDD Compliance: PASS
   • Approval: PASS
   • Status: LOCKED

Example: Complete Phase 3 TDD Section

## TDD Compliance Log

### R1: Add email validation

**Test:** `test/forms/validation.test.ts`

RED Phase (2026-02-21T10:15:00Z):
```bash
$ npm test test/forms/validation.test.ts
FAIL: Expected 'Email is required', got undefined

RED verified: PASS

GREEN Phase (2026-02-21T10:18:00Z):

• Added null check in submitForm() function
• Test passes GREEN verified: PASS

REFACTOR Phase (2026-02-21T10:22:00Z):

• Extracted validateRequired() helper
• All tests still passing REFACTOR complete: PASS

R2: Fix crash on empty array

Regression Test: test/utils/array.test.ts

RED Phase (2026-02-21T10:25:00Z):

$ npm test test/utils/array.test.ts
FAIL: TypeError: Cannot read property 'map' of undefined

RED verified: Bug reproduced PASS

GREEN Phase (2026-02-21T10:27:00Z):

• Added guard clause in processItems()
• Test passes GREEN verified: PASS

REFACTOR: N/A (minimal 2-line fix)

Verification

Full suite run: npm test Result: 47 passing, 0 failing

## References

- **REQUIRED:** Follow this skill for all Phase 3 implementation work