tdd

TDD — Test-Driven Development

Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. Violating the letter of this process is violating the spirit of this process.

Process

Red → Green → Refactor

1. Red: Write a failing test that describes the desired behavior

• Test name should read like a spec: it("returns 401 when token is expired") (reason: the test name IS your specification — it must communicate intent to future readers)
• Run the test — confirm it fails for the right reason (reason: a test that fails for the wrong reason gives false confidence)

1. Green: Write the minimum code to make the test pass

• Do not write more than needed — because premature optimization is the root of all evil; make it work first
• Do not optimize yet — because optimization without a passing test is speculation, not engineering
• Run the test — confirm it passes (reason: a passing test is the only proof the code works)

1. Refactor: Clean up without changing behavior

• Extract duplicates, rename for clarity, simplify — because readability matters more than cleverness
• Run tests again — must still pass (reason: refactoring without re-running tests is just renaming bugs)

Cycle

Repeat for each behavior. One test, one behavior, one cycle — because scope creep in a single test cycle leads to unverified code.

When to Trigger

• /go subagents: always — because autonomous agents without TDD produce unverified code
• New function or method being written
• Bug fix (write regression test first — because a bug that happened once will happen again without a guard)

Anti-Rationalization

| Excuse | Rebuttal | What to do instead |

|--------|----------|--------------------|

| "This is too simple for tests" | Simple code still breaks. The Beyonce Rule applies: if you liked it, you should have put a test on it. | Write the test anyway — it takes 30 seconds and catches edge cases. |

| "I'll write tests after" | That's documentation, not specification. Tests written after confirm what you built; tests written before define what you should build. | Write the test first. If you can't describe the behavior, you don't understand the requirement. |

| "Tests slow me down" | 15 minutes of TDD saves hours of debugging regression bugs later. | Time the cycle — Red-Green-Refactor is usually faster than debug-after-deploy. |

| "I'll just test manually" | Manual tests don't catch regressions. Automate it once, save hours forever. | Write an automated test that runs on every commit. |

| "The types guarantee correctness" | Types check shape, not logic. add(a,b) can still return a-b. | Write a test that verifies the actual business rule, not just the type signature. |

| "I need to see the API shape first" | Spike freely, then delete and rebuild test-first. A throwaway spike is research, not implementation. | Spike, discard, then TDD the real implementation from what you learned. |

Evidence Required

Before claiming TDD is done, show ALL of these:

• [ ] Failing test output (Red phase): the test name and failure message
• [ ] Passing test output (Green phase): ✓ with the same test name
• [ ] Test covers behavior, not implementation (no mocking internals)
• [ ] Refactor step completed OR explicitly noted as unnecessary with reason

No evidence = not done. "I wrote tests" without showing output is not TDD.

Red Flags

• Writing implementation before any test exists
• Test that tests implementation details instead of behavior
• Skipping the refactor step
• Multiple behaviors in one test