tdd

# Test-Driven Development

Guide the user through Red-Green-Refactor cycles to implement a feature or fix a bug test-first. Each cycle: write a failing test (Red), write the minimum code to pass it (Green), clean up while tests stay green (Refactor). One behavior per cycle.

This skill is for **new features** and **bug fixes** — not refactoring. For restructuring existing code without changing behavior, use `/optimus:refactor` instead (existing tests verify behavior is preserved).

### The Iron Law

**No production code without a failing test first.** If implementation code is written before its test, delete it entirely and begin the cycle fresh. Do not preserve it as reference, do not adapt it — write the implementation from scratch once the failing test exists. This is the non-negotiable foundation of every step that follows.

> **Coming from plan mode?** TDD runs in **normal mode**, in a fresh conversation. If you were iterating on a plan-mode prompt generated by `/optimus:brainstorm` or `/optimus:jira`, **toggle plan mode off without approving** (see `$CLAUDE_PLUGIN_ROOT/references/skill-handoff.md` for client-specific controls), let Claude append the "Refined plan" section to the spec or JIRA doc, then start a fresh conversation before invoking this skill — TDD will auto-detect the updated doc.

## Step 1: Pre-flight

Read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` for workspace detection. If a multi-repo workspace is detected, process each repo independently: run Steps 1–9 inside the repo the user is targeting. If ambiguous, ask which repo.

### Verify prerequisites

Check that `.claude/CLAUDE.md` exists. If it doesn't, stop and recommend running `/optimus:init` first — coding guidelines and project context are essential for the Refactor step.

Load these documents (they affect quality at every step):

| Document | Role | Effect on skill |
|----------|------|-----------------|
| `.claude/CLAUDE.md` | Project overview | Tech stack, test runner command |
| `coding-guidelines.md` | Code quality reference | Applied during Refactor step |
| `testing.md` | Testing conventions | Test file location, naming, framework, mocking patterns |
| `docs/product/tech-stack.md` *(if present)* | SDD steering — target stack | Low-priority context for Step 3 decomposition and Refactor |
| `docs/product/mvp-prd.md` *(if present)* | SDD steering — MVP scope | Low-priority context that informs decomposition |

The two `docs/` rows are the optional spec-driven-development steering cascade (scaffolded by `/optimus:spec-init`). Load them **only if they exist**; they *inform* decomposition and the Refactor step but never replace the task source or the behavior decomposition. See `$CLAUDE_PLUGIN_ROOT/references/sdd-mapping.md` for the precedence contract.

**Monorepo path note:** Read the "Monorepo Scoping Rule" section of `$CLAUDE_PLUGIN_ROOT/skills/init/references/constraint-doc-loading.md` for doc layout and scoping rules. When running TDD inside a subproject, load that subproject's `testing.md`, not another subproject's.

### Verify test infrastructure

Locate the test runner command from `testing.md`, `CLAUDE.md`, or project manifests (`package.json` scripts, `Makefile`, `Cargo.toml`, etc.). Run it once to confirm it works.

- **Tests pass** — proceed to Step 2 (Suitability Analysis)
- **Tests fail** — stop and report. Existing failures must be resolved before TDD can begin (a failing suite makes Red/Green indistinguishable)
- **No test runner found** — stop and recommend running `/optimus:init` first to set up test infrastructure (framework, runner, coverage tooling, `testing.md`). For a project with no code or detectable stack yet, tell the user to pick **Scaffold new project** when init asks — init builds a starter stack, then sets up the runner on it (so this is not a dead-end).

## Step 2: Suitability Analysis

Before starting TDD cycles, analyze whether the user's task is a good fit for test-driven development.

### Gather the task

Resolve the task description with the shared cascade in `$CLAUDE_PLUGIN_ROOT/skills/tdd/references/spec-context-detection.md` (explicit `docs/specs/`/`docs/jira/` reference → build-spec auto-discovery → JIRA auto-discovery → none, plus long-spec distillation to a single-sentence goal).

If that cascade resolved a task description (the user accepted a spec or JIRA context), use it — skip the gathering below. Otherwise, if the user provided a task description inline (e.g., `/optimus:tdd "Add auth endpoint"`), use it. Otherwise, use `AskUserQuestion` — header "TDD scope", question "What feature or bug fix do you want to implement with TDD?":
- **New feature** — "Implement a new capability (e.g., 'Add user authentication endpoint')"
- **Bug fix** — "Fix a bug by reproducing it with a test first (e.g., 'Login fails when email has uppercase')"

Whatever the source — a spec or JIRA context the cascade resolved, an inline argument, or the answer above — apply the shared reference's **Distillation** step to the final task description: if it runs longer than ~2-3 sentences, distill it to a single-sentence goal and confirm via `AskUserQuestion` before proceeding.

Detected context feeds into this task-gathering — it does NOT bypass Step 3 decomposition. TDD still independently decomposes the goal into behaviors, except when the build spec has a `## Scenarios` section in Given/When/Then form (see the scenario-driven shortcut in Step 3).

> **Prefer a self-orchestrated parallel build instead of supervised cycles?** `/optimus:workflow` implements the same spec by having Claude design and run a Claude Code dynamic workflow (test-first as a quality bar, no mid-run checkpoints, more tokens). Use TDD when you want supervised, interactive test-first discipline; use `/optimus:workflow` for a large or parallelizable spec where one linear pass is slow.

### Analyze suitability

Examine the task description against the codebase and classify it:

**Suitable for TDD** —