tdd

Test-Driven Development

Write test first. Commit it red. Write minimal code to pass. Commit green. Refactor.

Core principle: tests verify behavior through public interfaces, not implementation. Code can change entirely; tests shouldn't. A test that breaks when you rename an internal function — with no behavior change — was testing implementation. Delete it.

No watched failure = no proof the test tests the right thing. Commit history is the evidence; hooks check its structure.

See tests.md for examples and mocking.md for mocking guidelines.

Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST COMMITTED FIRST.

Wrote code before the test? Delete it. Implement fresh from tests. Delete means delete. Exceptions (throwaway prototypes, generated code, config) need human sign-off. Thinking "skip TDD just this once"? That is rationalization.

1. Plan (before any code)

Use the project's domain glossary so test names and interface vocabulary match the codebase; respect ADRs in the area you touch.

• List the behaviors to test, not implementation steps. Prioritize critical paths and complex logic — you can't test everything.
• Design interfaces for testability; identify opportunities for deep modules (small interface, deep implementation)
• Confirm the public interface and the priority behaviors with the user, then proceed.

2. Vertical slices, not horizontal

DO NOT write all tests, then all implementation. That is horizontal slicing and it produces crap tests: written in bulk they test imagined behavior and the shape of things (signatures, data structures), go insensitive to real changes, and commit you to test structure before you understand the code.

Work in vertical slices — one test → one implementation → repeat. Each test responds to what the last cycle taught you.

WRONG (horizontal):  RED: t1 t2 t3 t4   GREEN: i1 i2 i3 i4
RIGHT (vertical):    t1→i1  t2→i2  t3→i3 ...

The first slice is a tracer bullet: it proves the path works end to end.

3. Commit protocol

One behavior = one RED commit + one GREEN commit. Multiple cycles per branch is fine; prefer one cycle in flight in Go/Rust repos (see markers).

Every commit — RED included — leaves the tree lint-clean. After each commit, run the repo's full hook suite over the whole tree (e.g. prek run --all-files): exit code 0 and no files modified. An auto-fixer changing files IS a failure — apply the fix and amend it into the commit that introduced the problem before starting the next cycle. CI evaluating only the PR head never excuses a dirty intermediate commit; per-commit hygiene is verified here, at commit time, or not at all.

STUB commit (only when the RED test needs a missing API surface)

A RED commit is red on tests only: lint, format, and type checks still pass on it. When the new test calls a function, method, or parameter that does not exist yet, type checking would fail — so first commit a minimal signature-only stub as its own commit, prefix chore(stub):. Signature + docstring, zero behavior: a new callable raises NotImplementedError; a new parameter is accepted and ignored. This is the one sanctioned exception to the Iron Law: a stub defines interface, and must contain no implementation — any logic in a stub commit is production code without a failing test. Skip this step entirely when the surface already exists.

RED commit

• Write one failing test. One behavior, clear name, real code — no mocks unless unavoidable.
• Run it unmarked; watch it fail for the right reason (feature missing — behavior wrong, assertion fails, or the stub's NotImplementedError — never a typo, import error, or missing symbol). Passes immediately? It tests existing behavior — fix the test.
• Add the marker (below), suite green, commit. Tests only, prefix test(red):.

Go/Rust build-tag/ignore markers exclude tests from the normal suite, so a red-tests CI job must run only the marked tests and expect failure (no-op when none exist). Its exit code is aggregate: two red tests in flight, one wrongly passing → the job still passes. Strict markers catch this per-test; the job doesn't.

GREEN commit

• Simplest code that passes. YAGNI — no speculative generality.
• Remove this cycle's red markers. No other test changes in this commit.
• Full suite green, output pristine. Fails? Fix the code, not the test. Prefix feat:/fix:.

REFACTOR (after green only)

Remove duplication, improve names, extract helpers, deepen modules. Tests stay green, no new behavior, separate commit. Never refactor while red. Then start the next cycle.

After all tests pass, look for refactor candidates:

Enforcement — and its limits

lint-red.sh (ships with skill; wire into prek + CI): staged/commit modes check that test(red): commits touch only test files and add a marker, others add none; merge mode rejects any markers in tree; if Go/Rust markers are present, a red-tests job must exist.

Hooks verify commit structure and marker hygiene. They do not verify you ran the unmarked test and watched it fail for the right reason — that stays on you. Same for per-commit lint: an installed pre-commit hook blocks dirty commits at commit time, but where no hook is installed (fresh remote environments), the after-every-commit --all-files run is manual discipline — do it anyway. Strict markers partially compensate (XPASS catches tests of already-existing behavior). "Lint passed" ≠ "TDD verified."

Good tests

// Good — tests real behavior (vitest; jest: it.failing)
test.fails('retries failed operations 3 times', async () => {

Red flags — STOP, delete, restart

Unmarked test passes before implementation exists · can't explain why the test failed · weakening an assertion in GREEN to make it pass · testing the mock · "just this once" · "I'm being pragmatic, TDD is dogmatic."

Read testing-anti-patterns.md to avoid common pitfalls.

Rationalization table

When stuck / debugging

Don't know how to test → write the wished-for API and assertion first. Found a bug → write a failing test reproducing it, then run the full protocol. Never fix a bug without a test.