TDD Workflow
Purpose
Turn an acceptance criterion into executable evidence before production code changes. This skill owns the test contract and proof; service-implementation owns production edits.
When a route also includes service-implementation, this skill owns the test contract, red evidence, anti-overfit criteria, and reproduction commands. service-implementation owns the production code change under that contract. When this skill is used alone, it may execute the full red/green/refactor loop itself.
Change context
- Read
references/tdd-loop.md.
- State the changed behavior and the acceptance criterion it satisfies.
- Choose the lowest test level that can prove the behavior without mocking away the risk.
- Confirm the repository's test command and current framework behavior before writing the test.
Change method
- Write one test for one observable behavior and run it before changing production code.
- Confirm that it fails because the behavior is missing or wrong, not because the test setup is broken.
- Hand
service-implementation the expected behavior, owned files, prohibited shortcuts, and exact verification command.
- After implementation, run the new test and the affected suite. Do not weaken assertions to obtain a pass.
- Add one meaningful boundary, invalid-input, or failure-path case that the first test did not cover.
- Refactor only while the affected suite remains green; use
engineering-quality when structure or maintainability is part of the change.
- Map each covered acceptance criterion to a test file and list anything still unproved.
Engineering constraints
- Use current test-runner documentation when syntax, fixtures, matchers, or isolation behavior is uncertain.
- Record what the chosen test level proves and what it cannot prove.
- Do not require test-first work when no automated test can provide useful evidence; document the alternative verification path instead.
- Never delete, skip, or weaken an existing test solely to make a change pass.
Evidence
- Failing test and observed failure reason
- Implementation contract for
service-implementation
- Passing result for the new test and affected suite
- Boundary or failure-path evidence
- Acceptance-criteria coverage map and reproduction commands
Ready when
- The initial failure is reproducible and relevant.
- The tests exercise public behavior and meaningful boundaries.
- Mocks model dependency contracts rather than reproduce the implementation.
- Every completion claim names the command and result.
- Test names describe behavior, not internal steps.
Handoff
Hand off test files, commands, failure-to-pass evidence, covered criteria, and remaining test debt to qa-eval.
References
references/tdd-loop.md: red/green/refactor loop, anti-overfit rules, and the per-language matrix of test runners and matchers.
1---2name: tdd-workflow3description: Define changed behavior with a failing test, verify the failure reason, hand a bounded implementation contract to the code owner, then prove the fix with the affected suite and a boundary or failure case. Use for features, bug fixes, and behavior-preserving refactors where an automated test can provide useful regression evidence.4---56# TDD Workflow78## Purpose910Turn an acceptance criterion into executable evidence before production code changes. This skill owns the test contract and proof; `service-implementation` owns production edits.1112When a route also includes `service-implementation`, this skill owns the test contract, red evidence, anti-overfit criteria, and reproduction commands. `service-implementation` owns the production code change under that contract. When this skill is used alone, it may execute the full red/green/refactor loop itself.1314## Change context15161. Read `references/tdd-loop.md`.172. State the changed behavior and the acceptance criterion it satisfies.183. Choose the lowest test level that can prove the behavior without mocking away the risk.194. Confirm the repository's test command and current framework behavior before writing the test.2021## Change method22231. Write one test for one observable behavior and run it before changing production code.242. Confirm that it fails because the behavior is missing or wrong, not because the test setup is broken.253. Hand `service-implementation` the expected behavior, owned files, prohibited shortcuts, and exact verification command.264. After implementation, run the new test and the affected suite. Do not weaken assertions to obtain a pass.275. Add one meaningful boundary, invalid-input, or failure-path case that the first test did not cover.286. Refactor only while the affected suite remains green; use `engineering-quality` when structure or maintainability is part of the change.297. Map each covered acceptance criterion to a test file and list anything still unproved.3031## Engineering constraints3233- Use current test-runner documentation when syntax, fixtures, matchers, or isolation behavior is uncertain.34- Record what the chosen test level proves and what it cannot prove.35- Do not require test-first work when no automated test can provide useful evidence; document the alternative verification path instead.36- Never delete, skip, or weaken an existing test solely to make a change pass.3738## Evidence3940- Failing test and observed failure reason41- Implementation contract for `service-implementation`42- Passing result for the new test and affected suite43- Boundary or failure-path evidence44- Acceptance-criteria coverage map and reproduction commands4546## Ready when4748- The initial failure is reproducible and relevant.49- The tests exercise public behavior and meaningful boundaries.50- Mocks model dependency contracts rather than reproduce the implementation.51- Every completion claim names the command and result.52- Test names describe behavior, not internal steps.5354## Handoff5556Hand off test files, commands, failure-to-pass evidence, covered criteria, and remaining test debt to `qa-eval`.5758## References5960- `references/tdd-loop.md`: red/green/refactor loop, anti-overfit rules, and the per-language matrix of test runners and matchers.
ashermahonin