# TDD from Spec

Use when a feature spec doc already exists in `docs/`. Covers steps 2 and 3 of the feature workflow: write failing tests first, then implement to make them pass.

## Step 1 — Read the spec

Open the feature spec doc. Identify every behavior that needs to be verified: API contracts, state transitions, UI interactions, edge cases.

## Step 2 — Write failing tests (do not implement yet)

Write all three layers before touching any production code:

- **Unit tests** (`tests/<feature>.test.ts`) — pure logic, no DB, fast
- **Integration tests** (`tests/<feature>.integration.test.ts`) — routes and agents hitting a real DB, following the pattern in `respond-with-s-fields.integration.test.ts`
- **E2E tests** (`tests/e2e/<feature>.spec.ts`) — Playwright flows covering the golden path and key edge cases

Run the suite. **Every new test must fail at this point** — if a test passes before implementation exists, it is not testing the right thing. Fix it until it fails for the correct reason.

## Step 3 — Implement to pass

Write well-structured, production-quality code that makes the failing tests green. Do not add *behavior* that no test covers — but do not dumb down the implementation to satisfy that constraint. Good architecture, clear naming, and solid error handling are always in scope. The guard is against untested feature creep, not against quality.

Run `pnpm test` after each logical unit of implementation. Do not batch all implementation and run once at the end.

## Step 4 — Verify twice consecutively

Run the full suite twice in a row without changing any code. Both runs must be green. This catches flakiness before it reaches the branch.

## Step 5 — Reconcile and confirm

- Check test coverage matches every behavior listed in the spec
- Flag any spec behavior that has no test (do not silently skip it)
- Report the final pass count to the user and stop — do not commit unless explicitly asked