---
name: test-driven-development
description: Use when adding behavior that can be tested. Write a failing test first, then the minimum code to pass it, then refactor. Avoids over-built and untested implementations.
---

# Test-Driven Development

Use when adding or changing behavior that has a testable contract (function returns, API responses, CLI output, state changes).

## Cycle

1. **Red** — write the smallest failing test that captures the desired behavior. Run it. Confirm it fails for the *expected* reason (not import error, not typo).
2. **Green** — write the minimum code to make it pass. No extra features, no speculative abstractions.
3. **Refactor** — clean up while tests stay green. If a refactor breaks a test, the refactor was wrong, not the test.

## Rules

- One failing test at a time. Do not stack red tests.
- The test name must describe the behavior, not the implementation (`returns_404_when_user_missing`, not `test_get_user_2`).
- If you cannot write a failing test first, the change is probably not testable behavior — say so and proceed without TDD rather than faking it.
- Show the user the test output (red, then green) — don't claim it passes without evidence.

## When NOT to use

- Pure refactors with no behavior change (existing tests are the safety net).
- One-off scripts or exploratory spikes.
- UI tweaks where visual inspection is the real verification.

## Handoff

Pair with `verification-before-completion` to confirm the full suite still passes before declaring done.