---
name: tdd
description: Use when implementing or fixing production code with tests.
---
# TDD

If `topology=multi-module` (triage announcement or coordinator spec/plan declaration), read `../references/multi-module.md`. Run implementation and local acceptance inside the task's registered repository/module. Update that module's spec and plan; update the coordinator only for shared-contract reality or workspace state.

## Acceptance mode

Read the current plan task's `acceptance:` (or equivalent).

**Automated acceptance** (test, command, or script that must fail before the change and pass after):
- **No production code without a failing check first.** Wrote code before the failing check? Delete it. Rewrite from the check.
- RED (fail for the *right reason*) → GREEN (minimum to pass) → refactor → **sync docs** → commit → flip the plan checkbox.

**Manual acceptance** (explicit steps + expected result in the plan — config, docs, infra, prompts, content, or other non-testable deliverables):
- Do **not** invent an automated test solely to satisfy RED-GREEN.
- Perform the manual check; keep the change minimal; run any declared mechanical checks; **sync docs**; commit when appropriate; flip the plan checkbox.

**No acceptance at all** (prototypes, generated code, throwaway scripts only): ask the user before writing production code.

## After green / manual pass

**edit `docs/staging/plans/YYYY-MM-DD-<topic>.md` and change this task's `- [ ]` to `- [x]`. Do not start the next task without this edit.**

**Sync docs** means:
- If staging spec exists (`docs/staging/specs/*.md`): update it to match code reality.
- If no staging spec (small task): update living docs (README, tech-spec, comments) directly.

When local module tasks are complete and green, run the coordinator's cross-module acceptance against the current workspace contents before handing off to `ship`.

For a linked multi-repository change, defer commits until integration passes, then follow the commit protocol in `../references/multi-module.md`. This is the exception to the per-cycle commit order above. If any commit fails, stop at `partial-commit`; never rewrite or discard completed commits automatically.

## Refactor

Passing tests are not a quality bar.

`<gate>` Before committing: (1) run lint/format/typecheck — green if declared; (2) evaluate against `convention`; (3) assess design — coupling, cohesion, abstraction, idiomatic for the stack. State what you ran, assessed, and changed — or why not. See `../references/quality.md`. `</gate>`

## Don't
- Test passes without the impl (tests nothing).
- Mock the unit under test (tests the mock).
- Assert many behaviors in one test (split).
- Skip "watch it fail" when acceptance is automated (you don't know what it tests).
- Edit the test to match buggy code (tests the bug).
- Add abstractions not required by the current acceptance (GREEN phase — not refactor).
- Edit files outside the failing check's scope.
- Create ad-hoc summary, notes, or analysis files not defined in the plan or required by a loaded skill.