# Tdd Workflow

> 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.

- Skill: `ashermahonin/tdd-workflow` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ashermahonin/tdd-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ashermahonin/tdd-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ashermahonin (https://skillmd.com/u/ashermahonin)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/ashermahonin/tdd-workflow

---


# 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

1. Read `references/tdd-loop.md`.
2. State the changed behavior and the acceptance criterion it satisfies.
3. Choose the lowest test level that can prove the behavior without mocking away the risk.
4. Confirm the repository's test command and current framework behavior before writing the test.

## Change method

1. Write one test for one observable behavior and run it before changing production code.
2. Confirm that it fails because the behavior is missing or wrong, not because the test setup is broken.
3. Hand `service-implementation` the expected behavior, owned files, prohibited shortcuts, and exact verification command.
4. After implementation, run the new test and the affected suite. Do not weaken assertions to obtain a pass.
5. Add one meaningful boundary, invalid-input, or failure-path case that the first test did not cover.
6. Refactor only while the affected suite remains green; use `engineering-quality` when structure or maintainability is part of the change.
7. 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.