---
name: tdd
description: Develop one observable behavior at a time through a proven red-green-refactor cycle. Use only when the user explicitly requests TDD, red-green-refactor, or test-first development, or when an applicable repository policy requires test-first work. Skip ordinary requests to add tests, fix code, review, research, or run disposable spikes.
---

# Test-Driven Development

1. Confirm the explicit TDD trigger or applicable test-first policy. Inspect the behavior contract, package root, test commands, configured discovery, existing test levels, and nearby tests of the same role. Place and name tests according to the active runner and local precedent. Do not impose `.spec`, `.test`, a separate test tree, or another ecosystem's fixture layout.
2. When acceptance criteria govern the change, let `implement-and-verify` own criterion coverage and final evidence. Let this skill own the order of each behavior cycle. Apply `production-code-quality` to retained production code without duplicating its language or quality rules here.
3. Derive a short behavior list from the approved criteria and domain scenarios. Select the smallest vertical behavior whose result is observable through a stable public seam or the narrowest useful boundary. Read [test quality](references/test-quality.md) when the oracle, boundary, or fixture is nontrivial. Read [test doubles](references/test-doubles.md) only when a collaborator cannot be used safely and deterministically.
4. **Red:** write one runnable test with an expected result derived independently from the implementation. Use the minimum representative fixture. Run the focused repository-native command and prove that the test fails because the behavior is missing or incorrect, not because of syntax, setup, environment, or an unrelated defect. Record the test identifier, command, status, and intended failure signal. If the required behavior already passes, do not manufacture red. Preserve the passing characterization or regression evidence and choose an unmet behavior, or report that a red cycle is not applicable.
5. **Green:** make the smallest complete production change that satisfies the selected behavior and its required failure path. Do not add speculative abstractions, options, dependencies, or cleanup. Do not hard-code known test outputs, fixture identities, filenames, paths, timestamps, seeds, or test-only branches in production. Do not weaken an assertion, expected error, tolerance, snapshot, or fixture merely to obtain green. Run the same focused command and observe it pass, then run the nearest relevant existing tests.
6. **Refactor:** refactor only from a green state and only for a concrete improvement in names, duplication, cohesion, testability, or an established boundary. Preserve behavior, avoid layout-wide cleanup and future-facing abstractions, and rerun the focused tests after each material refactor. A refactor is complete only when the same behavior remains green.
7. Repeat one behavior at a time. Keep fixtures deterministic, locally owned, isolated from order and parallel workers, and responsible for cleanup. Treat a retry as diagnosis evidence, not as a default fix for a flaky test.
8. Run the proportionate regression suite and configured build, type, or static gates after the final cycle. Use [cycle evidence](references/cycle-evidence.md) for multiple cycles or consequential behavior. Distinguish unrelated pre-existing failures from failures that prevent trustworthy evidence.
9. Inspect the final test and production diff. Confirm that every test can fail for a relevant defect, every oracle remains independent, no fixture value leaked into production logic, no assertion was weakened without an approved contract change, and every production hunk belongs to the current behavior.

Read the dated [source ledger](references/sources.md) only when refreshing or justifying this workflow, not during routine TDD.

Stop when the expected behavior is unresolved or a valid red or green observation cannot be obtained. Finish when each initially unmet behavior has an observed red and green result from a comparable command, refactoring remains green, relevant regression gates are accounted for, and no test-specific production logic or speculative work remains.