TDD

Test-Driven Development

Implement $ARGUMENTS using Test-Driven Development (TDD).

TDD Cycle

Repeat: Red → Green → Refactor

1. Red:    Write a failing test
2. Green:  Write minimal code to pass the test
3. Refactor: Clean up code (tests still pass)

Which test cases matter, and when to refactor, is judgment. The one thing that is not judgment is whether a run came out the way you expected: every test run in this skill goes through .claude/skills/_shared/run_tests.py, which turns "confirm failure" / "confirm success" into an exit code.

Who Does What (delegation-first)

Per .claude/rules/delegation.md, the lead does not write the cycles by hand. The split is fixed:

Only a single trivial cycle on a file already open in context stays with the lead (Self-Handle List item 2). Two or more cycles, or a module the lead has not read, is delegated. Independent modules are delegated in parallel in one message; they share no test file, so nothing serializes them.

The Red/Green Invariant

python3 .claude/skills/_shared/run_tests.py \
  --target tests/test_{module}.py --expect fail --label red-1

--expect fail|pass (required) and --target PATH (repeatable, at least one) are the whole interface; --label names the log file under .claude/logs/ (default run-tests), so a later cycle does not overwrite an earlier log.

Read observed in the JSON — a non-zero exit is not all the same red:

Exit codes: 0 observed matches --expect; 1 bad arguments — including a --target that does not exist (the mistyped path, caught before pytest runs) and a pytest usage error (exit 4, e.g. an unknown ::node id); 2 observed does not match --expect, or coverage is below --min-coverage; 3 external failure — no pytest runner available, a timeout (--timeout, default 600s), or a pytest internal error. On 1 and 3 the payload's observed is null: the script reports that it has no observation rather than guessing one.

Other payload fields: expected, runner, command, exit_code, summary, failed_tests (node ids from the short summary), coverage_percent, min_coverage, log_file, artifacts, error.

The runner is resolved, not hardcoded: uv run pytest when uv and a pyproject.toml are present, otherwise pytest from PATH, otherwise python -m pytest (probed for importability first). --runner pins one explicitly. If none is available the result is exit 3, never a silent pass.

Implementation Steps

Phase 1: Test Design

1. Confirm Requirements

   • What is the input
   • What is the output
   • What are the edge cases

2. List Test Cases — record them with TodoWrite (one todo per case), so the remaining cases survive a context reset instead of living only in this conversation:

   - [ ] Happy path: Basic functionality
   - [ ] Happy path: Boundary values
   - [ ] Error case: Invalid input
   - [ ] Error case: Error handling

Which cases to write, and which boundary values matter, is domain reasoning — never delegate it to a script.

Phase 2: Red-Green-Refactor

Step 0: Hand the Cycles Off

Delegate the Red-Green-Refactor loop with the six-element prompt contract from .claude/rules/delegation.md. One delegation per module, all launched together:

Task tool:
  subagent_type: "general-purpose-sonnet"   # or general-purpose-opus, see the table above
  prompt: |
    Objective: Implement {module} by strict TDD, one test case at a time.

    Scope:
    - Write only tests/test_{module}.py and src/{module}.py. Touch nothing else.
    - Do not modify existing tests, and never skip, delete, or weaken an assertion.

    Inputs:
    - Test cases to implement, in this order: {the Phase 1 list}
    - Read .claude/rules/coding-principles.md and .claude/rules/testing.md first.
    - Existing conventions to follow: {paths of comparable modules}

    Acceptance checks — run these yourself, per cycle, and never skip Red:
      python3 .claude/skills/_shared/run_tests.py \
        --target tests/test_{module}.py --expect fail --label red-{n}
      python3 .claude/skills/_shared/run_tests.py \
        --target tests/test_{module}.py --expect pass --label green-{n}
    A Red that exits 2 with observed=passed/collection_error/no_tests_collected
    is not a Red: fix the test, not the production code, and re-run.

    Output shape:
    ## Cycles completed (case -> red label -> green label)
    ## Files changed
    ## Deviations from the requested test cases, and why
    ## Anything that did not go green

    Context discipline: return this summary only; the run logs stay in
    .claude/logs/ and are referenced by label, not pasted.

Then verify rather than trust: re-run run_tests.py --expect pass yourself and read the diff. A reported cycle with no matching run_tests.py exit 0 did not happen. If a cycle came back unfinished, escalate it (general-purpose-opus or codex-debugger) instead of re-sending the same prompt to the same tier.

The steps below are the contract the delegate follows — and what the lead runs directly in the single-trivial-cycle case.