/supergraph:tdd

Requires healthy index_status for CBM_PROJECT (see references/codebase-memory-contract.md with codebase-memory-mcp); if stale/degraded → index_repository before graph calls.

Strict TDD for features, bug fixes, refactors.

Iron Law: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Delete means delete: Production code written before verified failing test → delete and restart from RED.

When

Full TDD: new features, behavior changes, refactoring. Fast TDD: bug fixes (add regression test → RED verify → minimal fix). Ask to skip: config-only, generated code, throwaway prototype, docs-only.

State Machine (in order, never skip)

needs_test → red_verified → green_verified → refactor_allowed → complete

Steps

0. Announce

"🔴 /supergraph:tdd — TDD: [full|fast] for [behavior]..."

1. Identify One Behavior

Behavior: [single externally visible behavior]
Test file: [path] | Test name: [name]
Command: [focused test command]
Expected RED: [why it should fail before implementation]

One behavior per test. Public behavior, not internals. Real code over mocks.

For a falsifiability checklist, read writing-good-tests.md before finalizing a test.

2. 🔴 RED — Write + Verify in One Round

Write one failing test, then run immediately:

<write test> && $TEST_CMD <focused command>

Valid 🔴 RED: fails for the expected missing behavior, not syntax/import/typo.

Record evidence:

## TDD Evidence — 🔴 RED
- 🔴 RED: `[command]` → FAIL ([expected missing behavior])

Serena diagnostics (optional): See serena/SKILL.md:Setup — get_diagnostics_for_file before/after GREEN; use replace_symbol_body/rename_symbol over raw edits. Skip if SERENA_ACTIVE=false or unavailable.

Invalid RED → fix test setup, don't write production code yet.

3. 🟢 GREEN — Minimal Implementation

Write only enough code to pass the test. No abstractions, no cleanup, no extra features.

Delete any production code written before RED.

4. 🟢 GREEN Verify

Run focused test → broader suite:

## TDD Evidence — 🟢 GREEN
- 🟢 GREEN: `[command]` → PASS
- Suite: PASS

Failing test → fix code, not test. Other tests fail → fix now.

5. REFACTOR — Only After 🟢 GREEN

Rename, deduplicate, extract. No behavior changes. Re-run tests.

6. Complete

Before marking complete:

## TDD Complete
- Behavior: [behavior]
- Mode: full|fast
- RED verified: yes | GREEN verified: yes | Refactor: yes|none
- Tests: PASS

7. Report

Per behavior: ✅ /supergraph:tdd — behavior N: [brief]

Final:

✅ /supergraph:tdd complete
- Behaviors: N | Mode: full|fast | Tests: PASS | Lint: PASS
- Next: /supergraph:fix → /supergraph:verify → /supergraph:review

Fast TDD Path (Bug Fixes)

For bugs, skip full TDD ceremony:

1. Write one regression test that reproduces the bug
2. Verify it fails (RED) — the bug is proved
3. Write minimal fix only (GREEN)
4. Verify test passes — bug is fixed
5. No REFACTOR needed unless specified

Plan Integration

Plans must include TDD metadata per behavior task:

TDD:
- Behavior: [single behavior] | Test file: [path] | Test name: [name]
- RED command: `[focused test command]` | Expected RED failure: [missing behavior]
- Minimal GREEN change: [smallest implementation] | Mocking: none | [why unavoidable]

Executor Enforcement

• No production edits before red_verified
• Stop if RED passes immediately or fails for wrong reason
• Allow implementation only after valid RED, refactor only after GREEN

Review Triggers — Reject When

• Tests after implementation | No RED evidence | RED passed immediately | RED failed for wrong reason
• Implementation exceeds tested behavior | Bug fix lacks regression test
• Tests assert internals | Mocks hide integration risk

Anti-Patterns — Stop & Return to RED

Symptom	Fix
Production code before failing test	Delete, start RED
Tests after implementation	Next behavior test-first, remove untested code
"Too small to test"	Write one-liner test
Immediate pass accepted as RED	Test is wrong — revise
Pre-written implementation kept as reference	Delete, start fresh
Over-building before tests need it	YAGNI — remove

Mock Gate — Answer Before Mocking

1. What behavior is under test?
2. Is this mock isolating an external, slow, or flaky boundary?
3. What side effects does the real dependency provide?
4. Would this test fail if real behavior broke?

Reject tests that only prove mocks exist or were called.