---
name: pragmatic-tdd
description: Per-bead-type TDD playbooks — the operational procedure behind the pragmatic-tdd rule. Use when starting a bug/feature/refactor bead, when you need to write the failing test, or when proving red-then-green after the fact. Triggers on "pragmatic tdd", "starting a bug/feature/refactor bead", "write the failing test", "red-proof", "prove the test fails".
---

# Pragmatic TDD

The step-by-step playbooks for test-first work, by bead type. The goal is **signal**, not coverage (O17) — every test must be able to catch a real defect, or it should not exist. The always-on `pragmatic-tdd` rule states the obligations and exceptions; this skill is how you execute them.

This skill reads no overlay keys — the procedure is identical in every project.

## When to Use This Skill

Use this skill when:
- Implementing a **bug**, **feature**, **story**, or **refactor** bead
- You need to derive failing tests from acceptance criteria
- You wrote implementation before the test and need to prove the test would have failed (red-proof)
- A spike's prototype code is being promoted to a feature (the promoted work inherits the feature playbook)

Skip this skill when:
- Working a **spike** bead that stays investigative (deliverable is knowledge; tests optional)
- Working **decision**, **milestone**, **epic**, **chore**, **config**, or **docs** beads — no tests required; a test there is noise

The applicability policy (which bead types require tests, and the exceptions above) is owned by the always-on `pragmatic-tdd` rule. This skill carries the procedure for the types that qualify.

## Core Process

Where the evidence ledger is distributed (`scripts/tdd-ledger` in
kit-bootstrapped repos), record every observed red and green as you go —
`record-failing` the moment a required test fails, `record-passing` when it
passes — not only in the recovery ceremony below. The happy path produces
ledger evidence too.

### Bug beads — test first, always (O1–O5)

1. Write a test that reproduces the bug (the test MUST fail on the current code) (O1)
2. Verify the test fails for the right reason (feature missing, not typo/import error) (O2)
3. Write the minimal fix (O3)
4. Verify the test passes (O4)
5. **Scan for the bug pattern class across the codebase** (`rg`/`grep` for the anti-pattern, not the specific line). The bug often lives in more than one site — inlined at callsites, duplicated in sibling helpers, or copy-pasted into similar code. Fix every matching site in the same bead, or file follow-up beads before closing. Your reproducing test should fail on every unfixed site; if it doesn't, the test is scoped too narrowly. (O5)

A test that reproduces the bug proves the fix addresses the actual failure mode — but only for the site the test exercises. Step 5 is what prevents the "fixed one of three, shipped two" failure mode.

### Feature beads — ACs become tests (O6–O7)

1. Read the `--acceptance` criteria from the bead
2. Write failing tests that assert each AC (observable behavior, not internals) (O6)
3. Verify tests fail
4. Implement to make them pass
5. Verify all tests pass

### Story beads — same as feature beads (O8)

ACs become tests. Treat stories identically to feature beads.

### Refactor beads — safety net first (O9)

1. Check if behavioral tests already exist for the code being refactored
2. If not, write them BEFORE changing structure (test current behavior)
3. Refactor
4. Verify all behavioral tests still pass

The behavior shouldn't change — only the structure. Tests prove that.

## The red-proof ceremony (O16)

Evidence, not penance. The goal is proving the test catches the problem — not ritually deleting code. If you wrote implementation before the test:

1. Stash or revert the implementation change
2. Run the test
3. Confirm it fails — and fails for the right reason
4. Re-apply the change and confirm the test passes

The evidence that matters: the test fails without the fix and passes with it. How you obtain that evidence is flexible; that you obtain it is not.

**Durable form — the evidence ledger.** Record the red and green runs with `scripts/tdd-ledger` (distributed to `scripts/` in kit-bootstrapped repos): `tdd-ledger record-failing --test-id <id> --bead <bead-id> --output <test output>` at step 3, and `tdd-ledger record-passing` with the same ids at step 4. This appends to a committed `.tdd-ledger.jsonl`; `tdd-ledger verify` (run by CI where present) checks that every green has a prior red — converting the ceremony's evidence from close-reason prose into checkable data. Note: the CI workflow only actually blocks merges if the repo marks it as a required status check via branch protection — otherwise a red `verify` is advisory.

## Zero-signal test taxonomy — DO NOT WRITE THESE (O14)

Check every test you author against these five classes before it ships. (The tier1 test-signal review lens detects the same five classes by the same names — shared vocabulary is deliberate.)

1. **Testing mocks, not behavior.** `verify(mockService).fetchData(argX)` — proves the plumbing is connected, not that the feature works. If the mock changes, the test breaks. If the feature breaks, the test passes.

2. **Testing implementation details.** `expect(internalCache.size).toBe(3)` — breaks on any refactor, catches no real bugs. Tests should assert what the user/caller observes, not how the internals work.

3. **Testing what the type system enforces.** `expect(typeof getName()).toBe('string')` — TypeScript already does this. The test adds maintenance cost with zero signal.

4. **Tautological tests.** Agent writes `add(a, b) { return a + b }`, then writes `expect(add(2,3)).toBe(5)`. The test is a restatement of the implementation. It will never catch a real bug.

5. **Helper-only tests that skip the original callsite.** Fixing a bug by extracting or editing a pure helper and then testing the helper in isolation does not prove the bug is fixed at the callsite that triggered it. If the bug was reproduced via `foo()`, the regression test must drive `foo()` — or exercise the helper in the exact shape `foo()` uses it. Testing the helper alone leaves the original failure mode unprotected, and the fix may not even reach the callsite (e.g., if the callsite inlines the bug pattern rather than calling the helper). Pair this with step 5 of the bug-bead playbook to catch duplicated pattern sites.

**The guardrail (O15):** If a test would pass whether or not the feature actually works correctly, it's zero signal. Don't write it. (The rule states this verbatim too — advisory and procedural layers agree by construction.)

## Anti-Patterns

| Anti-Pattern | Why It Fails | Better Approach |
|--------------|-------------|-----------------|
| Skipping red | A test that never failed proves nothing — it may not exercise the bug at all | Write the test first; if you didn't, run the red-proof ceremony |
| Ritual code deletion | Deleting working code to "do TDD properly" wastes the work for zero extra evidence | Stash/revert, prove red, re-apply (O16) |
| Fixed one of three, shipped two | The reproducing test covers one site; sibling sites keep the bug | Pattern-class scan (bug step 5) before close |
| Testing the mock | Test passes when the feature is broken | Assert observable behavior, not plumbing (taxonomy class 1) |
| Helper-only regression test | Original callsite stays unprotected | Drive the test through the callsite that triggered the bug (taxonomy class 5) |
| Coverage as the goal | Tests written to hit a number, not to catch defects | Signal, not coverage — apply the guardrail to every test |