Skills/tdd/SKILL.md

name, description

name

description

tdd

Use when a feature description or tracker issue has test-specifiable behaviour — the "how it should work" can be pinned as a single failing test. Authors a minimal RED executable-spec and hands the GREEN side to implement mini-mode, exactly as a bug fix is handled. The alternative entry path to brainstorm→specify→planner for test-specifiable work; bounces back to brainstorm the moment the behaviour is not test-specifiable (genuine design forks). Distinct from the per-task TDD the implementer already practices inside implement.

tdd — executable-spec-first entry path

Violating the letter of these rules is violating the spirit.

Overview

For work whose desired behaviour is expressible as a test, the test is the spec. This skill is the alternative to the brainstorm → specify → planner design path: instead of a prose spec the user approves, it produces a single minimal RED executable-spec that says "this is how it should work", then treats that test exactly like a bug to be fixed — handing the GREEN side to the implement skill in mini mode, the same two-stage RED-first handoff debug uses for bugs.

Skipping the executable-spec stage — jumping straight to implementation because "the feature is obvious" — produces code with no failing test that ever pinned the intended behaviour, the exact gap RED-first exists to close.

This is not the per-task TDD the implementer already practices. Inside implement, the implementer writes a test per plan task as an inner-loop discipline. This skill is the entry-point form: it authors the one headline executable-spec that defines what the whole iteration delivers, before any plan or task exists. The two compose — this skill's headline test sits above the implementer's per-task tests, which drive it green from underneath.

The substantive process — turning a description into a minimal, autonomous RED test, the design-fork bounce-back, and the reactive decomposition into BLOCKER sub-tests when one iteration can't reach GREEN — lives in agents/tdd-author.md. That file is the single source of truth for the discipline; this skill file governs only trigger, dispatch, the orchestrator-side loop, and handoff.

When to Use / Skipping

Trigger this skill on:

• a feature description whose desired behaviour can be stated as a single falsifiable assertion ("calling X with Y returns Z", "endpoint /a rejects payload b with 422", "flag --foo makes the CLI emit bar")
• a tracker issue (feature / bug / unlabelled concrete task) whose body pins one observable behaviour

Use tdd instead of brainstorm only when the behaviour is test-specifiable. The honest test is the test of this: if you can write one minimal assertion that, green, means "the feature works as described", the work is test-specifiable and tdd owns it. If writing that assertion forces a choice between two or three plausible behaviours with real trade-offs, the work has a genuine design fork — that is brainstorm's job, and tdd must bounce back (see The Bounce-Back below). tdd never ratifies a guessed design into a test; guessing-a-design-as-a-test is the exact reactive-deference failure the brainstorm hard-gate exists to prevent, and it is no less a failure for being dressed as a test.

Skip tdd (and use the named alternative) for:

• an observed bug — use debug directly (it is already RED-first; tdd is for new behaviour, not a regression of existing behaviour).
• a cycle with genuine design forks — use brainstorm.
• a tidy iteration — use audit.
• a trivial mechanical edit — per the project's CLAUDE.md "trivial mechanical edits" carve-out.

This skill is a standard entry path, always available — one of the three design entries alongside brainstorm → specify → planner and specify → planner. Which one a given iteration uses is a fit decision per item, not a project setting.

The Iron Law

THE EXECUTABLE-SPEC (RED TEST) COMES FIRST — BEFORE ANY IMPLEMENTATION.
THE RED TEST IS MINIMAL AND AUTONOMOUS, AND IT ENCODES THE DESIRED BEHAVIOUR ("HOW IT SHOULD WORK"), NOT THE CURRENT ONE.
IT MUST FAIL FOR THE RIGHT REASON — FEATURE ABSENT — NOT A SYNTAX OR SCAFFOLDING ERROR.
NO FIX ATTEMPT IN THIS DISPATCH — THE GREEN SIDE GOES TO `implement` MINI-MODE.
IF THE BEHAVIOUR IS NOT TEST-SPECIFIABLE (DESIGN FORKS SURFACE), STOP AND BOUNCE TO `brainstorm`. DO NOT GUESS A DESIGN INTO THE TEST.
IF ONE ITERATION CANNOT REACH GREEN, DECOMPOSE INTO BLOCKER SUB-TESTS — DO NOT PUSH HARDER ON THE HEADLINE.

Every clause is non-negotiable.

Dispatch

Dispatch the tdd-author agent with the carrier fields it defines under Carrier contract in agents/tdd-author.md — source, intent, mode, blocked_report. That table is the authoritative definition of those fields; it is deliberately not restated here, so the two files cannot drift.

The agent writes the RED test to the working tree (uncommitted) and reports the handoff carrier for implement mini-mode. The agent does NOT commit anything, and does NOT write the feature — splitting RED (this skill) and GREEN (implement mini-mode) across two dispatches keeps the spec honest: the test is written before any implementation, so it genuinely pins the intended behaviour, not the post-hoc code path. The orchestrator decides whether to commit the RED test as a separate audit-trail commit before dispatching implement mini-mode, or to hand the dirty working tree directly to mini-mode (the mini-mode orchestrator's Phase-0 clean-tree check refuses the latter — so for an audit-trail flow the orchestrator commits the RED test first; for a streamlined flow it commits the combined RED+GREEN at the end of mini-mode). This is the same commit-shape decision debug hands the orchestrator.

The orchestrator-side loop

1. Dispatch tdd-author (mode: author).
   - BLOCKED (design fork) → go to The Bounce-Back.
   - NEEDS_CONTEXT → ask the user / read the issue, re-dispatch.
   - DONE → headline RED test in the working tree.
2. Dispatch `implement` mini-mode on the handoff carrier (drive GREEN).
   - DONE → the headline test is green; the feature shipped. Commit.
   - PARTIAL / BLOCKED → one iteration could not reach GREEN.
     Re-dispatch tdd-author (mode: decompose) with the implement
     BLOCKED report as `blocked_report`. Go to step 3.
3. tdd-author (decompose) carves the headline into a ladder of
   BLOCKER sub-tests and marks the headline blocked-on them.
   - DONE → the first sub-test is the next implement target.
     Return to step 2 with that sub-test as the carrier; when all
     sub-tests are green the headline test is un-blocked and
     re-targeted.
   - BLOCKED (design wrong) → go to The Bounce-Back.

The headline test is never edited to make it pass — it is the contract. It only changes shape via a deliberate decompose re-dispatch, which adds sub-tests below it; the headline's own assertion stays fixed.

The Bounce-Back

tdd returns to brainstorm whenever the work turns out not to be test-specifiable: either the tdd-author cannot write one honest headline assertion without choosing between plausible designs (author mode), or decomposition reveals the design itself is wrong rather than the granularity (decompose mode). The orchestrator:

1. Discards the working-tree test changes the agent left (git checkout -- . / rm the new test files — they were never committed, and a test that encodes a guessed design is worse than no test).
2. Invokes brainstorm with the design question the agent surfaced as the cycle request. From there the normal brainstorm → specify → planner → implement path runs.

The bounce-back is not a failure of this skill; it is the skill correctly refusing to ratify an un-chosen design into a test.

Handoff Contract

Direction	Carrier
user / issue → tdd	feature description or issue ref with test-specifiable behaviour
tdd → implement mini-mode	red_test_path + spec_summary + minimal-feature constraint (the carrier the agent defines under Output format)
tdd → tdd-author (decompose)	the implement BLOCKED report, on a GREEN that one iteration could not reach
tdd → brainstorm (bounce-back)	the design question the agent surfaced; working-tree test discarded

Anything beyond the one headline behaviour (a broader feature set, a refactor, a doc rewrite) is OUT of scope for the executable-spec iteration and gets queued for a separate one.

Common Rationalisations

Excuse	Reality
"The feature is obvious, just implement it — skip the RED test"	An obvious feature is 30 seconds to assert and 30 seconds to leave as a regression guard. Without the RED test, no test ever pinned the intended behaviour, and the next change that breaks it is silent.
"I'll write the feature and the test together"	Test-after proves nothing about whether the test would have failed before the feature existed. RED before GREEN — always; the split across two dispatches is the whole point.
"There are two plausible behaviours but I'll pick one and test it"	Picking one is a design decision, and a guessed design baked into a test is harder to dislodge than a prose spec. That is the bounce-back trigger — stop and go to brainstorm.
"One iteration didn't reach green, push harder on the headline test"	Pushing harder is hunch-driven. The disciplined move is to decompose into BLOCKER sub-tests; if decomposition can't find a test-specifiable smallest step, the design is wrong, not the effort.
"This is a bug, I'll use tdd because I like the flow"	A regression of existing behaviour is debug's job. tdd is for new behaviour. Using the wrong entry path muddies which tests guard regressions vs which define new contracts.
"Edit the headline test a little so implement can pass it"	The headline test is the contract. Editing it to pass is moving the goalposts. It changes only via a decompose re-dispatch that adds sub-tests below it; its own assertion is fixed.
"Decomposition keeps splitting — one more level will bottom out"	Two failed decomposition rounds means the design is wrong, not the granularity. Bounce to brainstorm rather than splitting a fourth time.

Red Flags — STOP

• "Skip the executable-spec, the feature is obvious"
• About to write any implementation before the headline test is RED
• The headline test fails on a syntax / import / scaffolding error, not because the feature is absent
• Writing one assertion required silently choosing between two or three plausible behaviours (→ bounce to brainstorm)
• About to edit the headline test so implement can pass it
• Pushing a third or fourth decompose round instead of bouncing to brainstorm
• Using tdd for a regression of existing behaviour (→ debug)
• About to git commit from inside the tdd-author agent (it never commits)

Cross-references

• Agent dispatched: agents/tdd-author.md — carries the authoring process, the design-fork bounce trigger, the reactive decomposition into BLOCKER sub-tests, the Common Rationalisations and Red Flags. The orchestrator does not execute these phases directly.
• Hand-off target (GREEN): ../implement/SKILL.md — runs the GREEN side as the implement-loop workflow in mode: "mini", after the orchestrator decides whether to commit the RED test separately or as part of the final commit. This is the same mini-mode handoff ../debug/SKILL.md uses.
• Bounce-back target: ../brainstorm/SKILL.md — reclaims the work when the behaviour is not test-specifiable.
• Sibling fast path: ../specify/SKILL.md — the other bounded entry path that shares this skill's bounce-to-brainstorm-on-fork discipline. Where tdd owns work whose behaviour one assertion can pin, specify owns work whose design the sources already resolve; both fall back to brainstorm when their precondition fails.
• Sibling RED-first skill: ../debug/SKILL.md — same two-stage RED→GREEN shape, but triggered by an observed bug rather than a new-behaviour description.
• Pipeline: ../docs/pipeline.md — tdd is a standard, always-available entry path; the graph and skip rules are fixed (not per-project).