Test-Driven Development (TDD)

Strategy before execution

Before every automated review or test/check pass, resolve a snapshot-bound REUSE, WAIT, RUN_MINIMAL, REVIEW_REQUIRED or STOP decision at its supported execution/dispatch boundary. Reuse valid coverage or join its active producer. Missing/stale decisions refuse; unknown coverage stays conservative. No model calls or recursive checks inside strategy. Status/HEAD changes, clean reviews and score targets alone never justify another expensive pass.

When to Use

• Implementing any feature or bugfix — before writing implementation code
• User says "write tests first," "TDD," or "red green refactor"
• NOT for: debugging existing failures (systematic-debugging), reviewing others' code (providing-code-review)

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

Wrong skill? Debugging existing failures → systematic-debugging. Reviewing others' code → providing-code-review.

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over. No exceptions.

Why Order Matters

RED must come before GREEN. Not as preference — as the entire mechanism.

1. Test-before defines what the code should do. Test-after verifies what the code already does. These are not the same thing. Writing tests after implementation is documentation, not TDD.
2. If you haven't watched the test fail, you don't know it tests what you think. A test that has never been red may pass because the feature exists, or because it's testing nothing, or because it's testing the wrong thing. You cannot tell. Only a prior red phase tells you.
3. GREEN without RED is theater. Any implementation will pass a test you wrote looking at the implementation. The discipline is writing the test before you know how it will be satisfied.
4. The order is the method. "I did TDD but in a different order" is not TDD. Skipping RED eliminates the only verification that your test is meaningful.

Common Rationalizations

Red-Green-Refactor

RED — Write Failing Test

Write one minimal test showing what should happen. One behavior, clear name, real code (no mocks unless unavoidable).

test('retries failed operations 3 times', async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error('fail');
    return 'success';
  };
  const result = await retryOperation(operation);
  expect(result).toBe('success');
  expect(attempts).toBe(3);
});

Verify RED — Watch It Fail (MANDATORY)

Run test. Confirm it fails for the expected reason (feature missing, not typo). Test passes? You're testing existing behavior — fix test.

GREEN — Minimal Code

Write simplest code to pass. Don't add features, refactor, or "improve" beyond the test.

Verify GREEN (MANDATORY)

Use strategy to select affected RED/GREEN coverage and genuinely missing project checks. Reuse unchanged passing evidence. Report every observed failure by name, distinguish regressions, and stop unchanged failed-input retries. GREEN requires the project's applicable coverage to be satisfied by valid producer evidence; it does not require another full suite after every edit.

REFACTOR — Clean Up

After green only: remove duplication, improve names, extract helpers. Keep tests green. Don't add behavior.

Repeat

Next failing test for next feature.

Verification Checklist

Before marking work complete:

• Every new function/method has a test
• Watched each test fail before implementing
• Each test failed for expected reason
• Wrote minimal code to pass each test
• All tests pass, output pristine
• Tests use real code (mocks only if unavoidable)
• Edge cases and errors covered

Can't check all boxes? You skipped TDD. Start over.

When Stuck

Red Flags — STOP and Start Over

Any of these means you are violating TDD:

• Writing implementation code before any failing test exists
• "I already manually tested it"
• "Tests after achieve the same purpose"
• "It's about the spirit, not the ritual"
• "This is different because..."
• "The test I would write is obvious"
• Reaching for GREEN before confirming RED (test must actually fail first)
• "I'll add tests in the refactor phase"

All of these mean: Delete code. Start over with TDD.

Failure Modes

Writing Good Tests

When adding mocks or test utilities, read @writing-good-tests.md: name the break each test catches, derive expected values independently of the code under test, and exercise real behavior instead of mock existence.

Companion Skills

• debate — when test architecture decisions arise (≥3 approaches to test a complex feature)
• systematic-debugging — when tests fail for non-obvious reasons, switch to root-cause investigation
• verification-before-completion — after TDD cycle, verify ALL tests pass before claiming done
• feature-development: Full feature workflow
• subagent-driven-development: TDD within sub-agent tasks
• quantitative-decision-gate: Test strategy decisions