building-tdd

name	building-tdd
description	Use red-green-refactor for a feature or bug fix when the user asks for test-first work.
metadata	{"internal":true}

building-tdd

Red-green-refactor in vertical slices — one test → one implementation → repeat. The loop is pnpm test <file> going red then green. Seam doctrine (public interface, highest seam, vitest, no source-text assertions, member co-location vs wheelhouse test/repo/): test-layout. The deterministic core is every pnpm test / pnpm run check run; AI owns the residue — what to test and how to name the behaviour (code-first-then-ai).

Never: horizontal slices

Do NOT write all tests then all implementation. Tests written in bulk verify imagined behaviour — they assert the shape of data and signatures, pass when behaviour breaks, and outrun your understanding. One behaviour at a time.

1. Plan

Establish the project's behavioural vocabulary first — rg 'describe\(' test/ | head -20 to see how existing tests name behaviour, so your test names match. Then list the behaviours to test (not implementation steps) and the public interface under test. You can't test everything — pick the critical paths.

2. Tracer bullet

Write ONE test for ONE behaviour at the correct seam. Name the pnpm test <file> invocation. Watch it go red. Write the minimal code to make it green. This proves the path end-to-end.

3. Incremental loop

For each remaining behaviour: RED (pnpm test <file> fails) → GREEN (minimal code passes). One test at a time, only enough code to pass the current test, don't anticipate future tests, assert observable behaviour through the public interface — never internal structure or source text.

4. Refactor

Only after all tests pass. Run pnpm run check + pnpm run lint. Refactor with the green suite as your safety net; the tests shouldn't change (they verify behaviour, not implementation). prefer-vitest-guard and no-test-in-scripts-guard enforce the structural rules — this skill is the procedural loop they assume.

Completion criterion

Every chosen behaviour has a passing test that exercises it through the public interface, pnpm run check is green, and no test asserts implementation detail.

Handoffs

Use writing-fast-tests to pick the cheapest seam for each test you add — the unit tier is budgeted under a minute, and a spawned child costs ~68,000× an in-process call. Then reviewing-code for an independent branch review, and pushing for the complete release gate.