tdd

name	tdd
description	Test-driven development for factory builders. Use when a ship job implements at the issue's pre-agreed seams — the red -> green loop, one test then one minimal implementation per cycle, never a refactor while RED.

Test-Driven Development

TDD is the red -> green loop. This skill is the reference that makes that loop produce tests worth keeping. Consult it before and during the loop, not after. Name things with the codebase-design vocabulary (skills/codebase-design/SKILL.md), preloaded beside this skill.

Seams are pre-agreed, not interviewed

A seam is the public boundary you test at — the interface where you observe behavior without reaching inside. In this factory the seams are already agreed before you start: they're named in the issue body and the spec. A builder never interviews a user to find seams; if an issue names none, that's a spec gap to report, not a prompt to go ask someone.

Frozen checks under docs/checks/ are read-only grading — not your tests. They verify the slice from outside, after the fact. Write your own tests at the issue's named seams and run them yourself before you report. A green frozen check with no tests of your own is not done.

What a good test is

Tests verify behavior through the seam, not implementation details. A good test reads like a specification and survives refactors because it doesn't care about internal structure. See tests.md for examples and mocking.md for mocking guidance.

Anti-patterns

• Implementation-coupled — mocks internal collaborators, tests private methods, or verifies through a side channel. Tell: it breaks on refactor with no behavior change.
• Tautological — the assertion recomputes the expected value the way the implementation does, so it passes by construction. Expected values come from an independent source: a known-good literal, a worked example, the spec.
• Horizontal slicing — writing every test first, then all implementation. Work in vertical slices instead: one test -> one minimal implementation -> repeat, each test a tracer bullet answering what the last cycle taught you.

Rules of the loop

• Red before green. Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
• One slice at a time. One seam, one test, one minimal implementation per cycle.
• Never refactor while RED. Refactoring belongs to review, not the red -> green cycle.
• Mock at system boundaries only — external systems, time, randomness. Never your own modules.

Report only what you proved

Evidence-ground every claim: report only what a tool result from this session actually shows — the command output and exit code from a test you ran, not a claim of passing without the run behind it.