tdd git:20260717.120e9bbA

Immutable. This exact content is served forever at /api/v1/blob/949f986e0619ce78.

---
name: tdd
description: >-
  Test-driven development — write a failing test that names the behavior, watch
  it fail, implement the minimum to make it pass, then refactor with tests green.
  Works for new features, bug fixes, and behavior changes. Use when the user says
  "tdd", "test-first", "write tests first", or wants a change built test-first.
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
  - Edit
  - Agent
argument-hint: "[feature or behavior]"
---

# TDD: red, green, refactor

Write the test before the code. A test written first specifies the behavior,
fails for a known reason, and gives you a definition of done you can run. A test
written after tends to describe whatever the code happens to do — bugs included.

## Step 1: Find the test runner

Don't assume the command. Detect how this project runs and writes tests: look at
existing test files for the framework and conventions, and at the build/config
for the invocation (`go test ./...`, `npm test`, `pytest`, `cargo test`, …).
Match what's already there — same framework, same layout, same style.

## Step 2: Name the behavior as tests (RED)

State the change as concrete cases before writing any implementation:

- The main success path — the behavior actually requested.
- The edges — empty, zero, boundary, maximum, unexpected input.
- The failures — what should error, and how it should error.

Write these as tests. For a bug fix, the first test **reproduces the bug**. Keep
each test focused on one behavior with a clear name.

## Step 3: Watch them fail

Run the tests and confirm they fail — and fail for the *right* reason (the
behavior is missing), not a typo or an import error. A test you never saw fail
proves nothing. This is the gate: do not write implementation until you've seen
red.

## Step 4: Implement to green

Write the **minimum** code that makes the tests pass. No features the tests don't
demand, no speculative abstraction. Run the tests until they're green.

## Step 5: Refactor on green

Now improve the shape — naming, duplication, structure — with the tests staying
green the whole way. The tests let you clean up without fear; if one goes red, the
last change altered behavior, so undo it.

## Test what callers see, not how it's built

- Assert on observable behavior and return values, not private internals — tests
  bound to implementation break on every refactor and defeat Step 5.
- Keep tests isolated: no shared mutable state, no ordering dependency, each runs
  alone. Prefer real behavior; mock only what you can't run (network, clock,
  external services).
- Cover the edges and error paths, not just the happy case — that's where the
  bugs the persona is trying to prevent actually live.