Test Driven Development

Standing Mandates

• ALWAYS write a failing test before writing any implementation code.
• ALWAYS name the exact production change that would make a RED test fail before you run it — a falsifiability probe, not a hope.
• ALWAYS make the smallest possible change to turn RED to GREEN before refactoring.
• NEVER accept a passing test without evidence it can also fail for the right reason.

Test-Driven Development (TDD)

A test that has never been watched to fail is an unverified claim wearing a green checkmark. This skill treats every RED as a small experiment: state what would break it, run it, record what actually happened. GREEN only counts once that record exists.

Core principle: A passing suite is not evidence. A passing suite plus a recorded failure that happened for the predicted reason is evidence.

Dual-Mode Operating Map

This skill runs the same cycle whether you're working alone or the harness engine owns the run. What changes is who checks the evidence and where it's checked.

Not sure which mode you're in? If a harness pipeline invoked this skill, you're in harness mode — defer to its stage boundaries. Otherwise, default to solo mode and self-apply the same checks.

When to Use / When to Skip

Catching yourself thinking "I'll skip the probe just this once"? That thought is the signal to stop, not a reason to continue.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Code arrived before its test? Throw it away and rebuild from the test. Keeping it "for reference" or "to adapt" is the same violation wearing a different excuse — the fix is to not have it in front of you.

Process: Red-Green-Refactor

Cycle: RED → falsifiability probe → verify failure → GREEN → verify pass → REFACTOR → repeat.

Before writing any RED test, skim references/testing-anti-patterns.md — it pre-screens the test design against the usual mock-related traps (asserting on mocks, mocking without understanding side effects, test-only production methods) so you don't build a probe on top of one.

RED — Write One Failing Test

Pick one behavior. Name the test after that behavior, not after the code path.

test('opens the circuit after 3 consecutive failures', async () => {
  const breaker = new CircuitBreaker({ threshold: 3 });
  const failingCall = () => Promise.reject(new Error('down'));

  await breaker.attempt(failingCall).catch(() => {});
  await breaker.attempt(failingCall).catch(() => {});
  await breaker.attempt(failingCall).catch(() => {});

  expect(breaker.isOpen()).toBe(true);
});

Requirements: one behavior per test, a name that reads as a sentence about behavior, and real collaborators — reach for a mock only when a dependency can't be run in the test.

Falsifiability Probe (REQUIRED)

Before you run the test, write down the exact production change that would flip it to failing. This is not optional and it is not a review of some earlier note — it's a fresh commitment you make for every RED test, right now, before GREEN exists:

1. Name the breaking change. One sentence: "if the threshold counter is removed" or "if isOpen() always returns false." Be specific enough that someone else could make that exact change.
2. Run the test now, before any implementation exists, and confirm it fails.
3. Optional, after GREEN: apply the named breaking change to the working implementation and re-run the test. If it still passes, the test was never testing what you thought — fix the test before moving on. If it fails as predicted, revert the change; that failure is your proof the test has teeth.

A test you can't name a breaking change for is a test you don't understand yet. Don't run it — go back and clarify what behavior it's supposed to pin down.

RED Evidence Record

Every RED cycle produces one record — three fields, filled in as you go, not reconstructed afterward:

Keep this record with the test, in a commit message, or in your working notes — wherever the harness-mode evidence gate or your own solo-mode discipline can find it later. An "observed failure reason" that doesn't match what you predicted means stop and re-diagnose before writing any implementation.

Verify RED — Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts

If think-tool is available, use it here: does the failure text match the reason recorded above — feature genuinely absent — or does it look like a typo, a bad import, a syntax slip? Only the former is a valid RED.

Test passes immediately? You're exercising code that already exists. Rewrite the test.

Test errors instead of failing? Fix the error, rerun, until the failure is the one you predicted.

GREEN — Smallest Code That Passes

Write only enough to satisfy the test in front of you. Resist adding options, generality, or the "while I'm here" cleanup — that belongs in REFACTOR, and only if a test demands it.

class CircuitBreaker {
  private failures = 0;
  constructor(private opts: { threshold: number }) {}

  async attempt<T>(fn: () => Promise<T>): Promise<T> {
    try {
      const result = await fn();
      this.failures = 0;
      return result;
    } catch (e) {
      this.failures++;
      throw e;
    }
  }

  isOpen(): boolean {
    return this.failures >= this.opts.threshold;
  }
}

Verify GREEN — Watch It Pass

MANDATORY.

npm test path/to/test.test.ts

If think-tool is available, use it here: did the test pass because the behavior is now correctly implemented, or because an assertion got loosened on the way to green? Those look identical in a terminal and are not the same outcome.

REFACTOR — Clean Up on Green Only

If think-tool is available, classify every planned edit as structure-only (rename, extract, dedupe) or behavior-changing before touching anything. Proceed only with the structure-only ones — a behavior-changing edit needs its own RED first.

Remove duplication, sharpen names, extract helpers. Tests stay green throughout; if one goes red mid-refactor, that edit wasn't structure-only after all.

Repeat

Pick the next behavior. Next RED, next probe, next record.

Good Tests

When Stuck

Red Flags — Stop and Restart from RED

Hearing yourself reach for any of these is the signal, not a reason to continue:

• Writing implementation before the test exists
• A test that passed on the very first run
• Unable to say why a test failed
• "I'll add tests once this is working"
• "Already manually checked it, that's close enough"
• "Tests-after get us the same place"
• "It's fine, I'm honoring the spirit of it"
• "I'll keep the old code as reference while I write tests"
• "Too much time invested to throw this away now"
• "Strict TDD is dogma; I'm being practical"

Every one of these means: discard the code, restart from a failing test.

Debugging Integration

A bug report is a missing test wearing a different hat. Reproduce it as a failing test, name the falsifiability probe, then run the normal cycle. The passing test is your proof the bug is gone and your guard against it coming back.

Never patch a bug without a test that fails first for that exact reason.

Output Template

When applying TDD, produce, per cycle:

1. The failing test plus its falsifiability probe (breaking change named before GREEN)
2. The RED Evidence Record (test name, breaking change, observed failure reason)
3. Minimal implementation that turns it GREEN
4. Refactor notes, if any structure-only cleanup was done
5. The next test queued for the cycle

What Claude Does / What You Do

Related Skills

• completion:verification-before-completion — the solo-mode evidence gate this skill's GREEN step defers to
• harness:harness — the harness-mode QualityGate this skill's evidence trail feeds
• develop:test-master — generating tests for existing untested code
• develop:flaky-test-analyzer — diagnosing intermittent test failures