/tdd

description: Guides test-driven development — decomposes a feature or bug fix into testable behaviors, then runs Red-Green-Refactor cycles with a failing test before every implementation. Auto-detects specs from docs/specs/ or docs/jira/, creates a feature branch (optional worktree), commits per cycle, and pushes. Recommends /optimus:init (falls back to general best practices on your choice); requires a passing test suite.
disable-model-invocation: true
argument-hint: "[task description]"

Test-Driven Development

Implement a feature or bug fix test-first: for each behavior, write a failing test (Red), write the minimum code to pass it (Green), then clean up while tests stay green (Refactor). This skill builds new behavior — for restructuring without behavior change, use `/optimus:refactor`.

**The Iron Law: no production code without a failing test first.** If this cycle's implementation is written before its test, undo only that implementation using the ownership record below and begin the cycle fresh. Preserve pre-existing code and user edits; write the cycle's implementation once the failing test exists.

Coming from plan mode? TDD runs in normal mode in a fresh conversation; plan-mode iterations that feed it are review-only — see `$CLAUDE_PLUGIN_ROOT/skills/brainstorm/references/plan-mode-handoff.md`.

Step 1: Pre-flight

If `git rev-parse --is-inside-work-tree` does not return `true`, read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` and apply it; if a multi-repo workspace is detected, work inside the repo the user is targeting — ask which one if ambiguous. When it returns `true`, resolve the repository root with `git rev-parse --show-toplevel`, including in a linked worktree or subdirectory.

Preserve starting work

Record the current branch/HEAD and staged, unstaged, and untracked paths before setup or edits. These changes belong to the user unless the conversation explicitly includes them in this task. Existing authorization persists; ask only when ownership or scope is genuinely ambiguous. A new branch does not isolate dirty work, and a new worktree starts from committed state rather than carrying the user's dirty changes.

Before the first edit to each file in a cycle, record its existence and SHA-256 over its raw bytes. An empty Git status/diff does not prove those bytes are recoverable: index flags and filters can hide differences. Read a candidate HEAD/index blob with `git cat-file blob <blob-oid>`, capturing binary stdout; use Git as the rollback source only when its bytes exactly match the current file. Save that immutable blob ID and the verified hash. Otherwise copy the exact bytes to the private session scratchpad — or a temporary directory outside the repository when the host offers none — and verify the copy before editing. Keep the recovery source until the cycle is committed or safely rolled back.

For **every** edited path, record the last bytes/hash and existence written by the cycle, regardless of recovery source. Before any rollback, compare the current state with that last-written state. Restore or delete a whole file only on a match; if it changed independently, remove only identifiable cycle changes, preserving other work. If separation is uncertain, preserve it and show the ambiguity. Delete a newly created file only when it was absent at the cycle boundary and still matches the cycle's last version.

For restoration, load the saved blob or copy and verify its raw-byte hash before overwriting the original; preserve it on any read or verification failure. Restore those verified bytes directly, without checkout filters or reliance on the current HEAD/index. Never use hard reset, broad stash/pop, or cleanup as a substitute for this boundary; never replace the user's starting index or stage unrelated work.

If `.claude/CLAUDE.md` or `.claude/docs/coding-guidelines.md` is missing, recommend `/optimus:init` first; on the user's choice, continue with general best practices. Load:

• `.claude/CLAUDE.md` — project overview, tech stack, test runner command
• `.claude/docs/coding-guidelines.md` — applied during Refactor
• `testing.md` — test conventions: framework, file location, naming, mocking patterns. In a monorepo, load the target subproject's own `docs/testing.md` / `docs/` files; shared guidelines come from root `.claude/docs/`
• `docs/product/tech-stack.md` and `docs/product/mvp-prd.md`, only if present — low-priority steering that informs decomposition and Refactor but never overrides the task source (precedence: `$CLAUDE_PLUGIN_ROOT/references/sdd-mapping.md`)

Verify test infrastructure

Locate the test runner command (from `testing.md`, `CLAUDE.md`, or project manifests) and run it once:

• **Tests pass** — proceed
• **Tests fail** — stop and report; a failing baseline makes Red/Green indistinguishable
• **No runner found** — stop and recommend `/optimus:init` to set up test infrastructure (its Scaffold option covers projects with no code yet)

Then find a coverage command — first match wins: the coverage section of `testing.md`, a runner flag (`vitest --coverage`, `pytest --cov=.`, `go test -cover`, `dotnet test --collect:"XPlat Code Coverage"`), or a `package.json` coverage script. If found, run it once and record the `Before` percentage; Step 8 runs only the `After` measurement.

Step 2: Task and Suitability

Resolve the task with the cascade in `$CLAUDE_PLUGIN_ROOT/skills/tdd/references/spec-context-detection.md`. If nothing resolves and no inline argument was given, use `AskUserQuestion` — header "TDD scope", question "What feature or bug fix do you want to implement with TDD?", options **New feature** / **Bug fix**. Whatever the source, apply the reference's **Distillation** step to the final description. Resolved context feeds this step — it does not bypass Step 3 decomposition (except the scenario-driven shortcut).

Classify the task:

• **Suitable** — new features with testable behavior, bug fixes re