---
name: tdd
description: >
  Use when implementing any feature or fix outside code-forge workflow — enforces
  Red-Green-Refactor cycle with mandatory test-first discipline. Supports three modes:
  (1) Standalone — ad-hoc TDD for quick changes, (2) Auto-Analysis — runs the full
  spec-forge:test-cases analysis pipeline (project profile, four-layer deep scan,
  multi-dimensional coverage) then implements all cases via TDD, (3) Driven — reads
  a test-cases.md document and implements each case via TDD.
---

# Code Forge — TDD

## ⚡ Execution Entry Point

@../shared/execution-entrypoint.md

**For this skill:** start at **Step 0 (Determine Mode)**. If you catch yourself about to say "falling back to manual TDD", STOP and go to the indicated step.

---

Test-Driven Development enforcement for any code change, with built-in code analysis.

## When to Use

- Writing code outside of code-forge:impl workflow (ad-hoc changes, quick fixes)
- Adding tests to existing code that lacks coverage
- Implementing test cases from a spec-forge:test-cases document
- Any new feature, bug fix, or behavior change that needs test discipline

**Note:** code-forge:impl already enforces TDD internally. This skill is for work outside that workflow.

## Iron Law

**NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.**

No exceptions. Not for "simple" changes. Not for "obvious" fixes. Not when under time pressure.

## Design Discipline (Mandatory, Applies to All Modes)

Before any RED step in any mode (Driven, Auto-Analysis, Standalone), you MUST run the design-first pre-code checklist: read the relevant subsystem, consider the optimal interface-stable design, and decide whether to refactor existing code or add new code. The TDD cycle's REFACTOR step is the second enforcement point — every GREEN must be followed by a real consideration of whether the new code is the cleanest shape, not the most expedient one.

This discipline is the upstream defense against patch-first development. Read it once at the start of every session and again whenever you are tempted to add a new branch / wrapper / parallel module instead of refactoring:

@../shared/design-first.md

## Step 0: Determine Mode

Examine the arguments to determine the operating mode:

| Argument | Mode | Behavior |
|----------|------|----------|
| `@docs/.../test-cases.md` | **Driven Mode** | Read test cases document, implement each case via TDD |
| `@src/services/payment.ts` or specific code path | **Auto-Analysis Mode** | Analyze specified code, design cases, implement via TDD |
| Feature name or description (e.g., "add validation to user signup") | **Standalone Mode** | Classic TDD — write tests for the described change |
| Empty (no arguments) | **Auto-Analysis Mode** | Scan project for coverage gaps, design cases, implement |

## Driven Mode — Implementing from Test Cases Document

When a `test-cases.md` file is provided (generated by `spec-forge:test-cases`):

### D.1 Read and Parse

1. Read the test-cases document
2. Extract all test cases (TC-MODULE-NNN entries)
3. Identify which are already implemented (check existing test files for matching test names/IDs)
4. Filter to unimplemented cases
5. Sort by priority: P0 first, then P1, then P2

### D.2 Confirm Scope

Present to user:
- "{N} test cases found, {X} already implemented, {Y} remaining"
- "Implement: (A) all remaining, (B) P0 only, (C) P0 + P1, (D) specific modules?"

### D.3 Implement Loop

For each test case in scope:

1. **Read the case** — extract preconditions, steps, expected result, not-expected, test infra
2. **Set up test infrastructure** — if Test Infra is "Real DB", configure TestContainers or test database; if "Mock external", set up mock for the specified third-party service; if "Temp dir", create temp directory; if "N/A", no special setup needed
3. **RED** — Write a failing test that matches the case specification
   - Test name should include TC ID: `test("TC-AUTH-001: create user with valid email returns 201", ...)`
   - Preconditions become test setup (seed data, auth context, config)
   - Steps become test actions
   - Expected result becomes assertions
   - "Not Expected" becomes negative assertions where applicable
4. **VERIFY RED** — Run the test, confirm it fails correctly
5. **GREEN** — Write minimal production code to make it pass (if the code already exists and passes, the case was already covered — note and move on)
6. **VERIFY GREEN** — Run all tests, confirm clean pass
7. **REFACTOR** — Clean up if needed
8. **Report** — "TC-AUTH-001: DONE (test passes, implementation complete)"

### D.4 Progress Tracking

After each case, display progress:
```
TDD Progress: {completed}/{total} ({percentage}%)
  [x] TC-AUTH-001: Create user with valid email (P0) — DONE
  [x] TC-AUTH-010: Create user with duplicate email rejected (P0) — DONE
  [ ] TC-AUTH-011: Create user with invalid email format (P1) — next
  [ ] TC-AUTH-030: Create user should NOT bypass email validation (P1)
```

Ask: "Continue with next case, skip, or pause?"

### D.5 Completion

After all cases are implemented:
- Run full test suite
- Report: total cases implemented, all tests passing, coverage change
- Suggest: "Run `/code-forge:verify` to confirm completion"

## Auto-Analysis Mode — Scan and Test

When the user points to code or says "help me write tests" without a test-cases document.

**Iron Rule: Auto-Analysis uses the SAME full analysis as spec-forge:test-cases.** The only difference is the output — auto-analysis produces code directly instead of a document. The analysis quality must be identical.

### A.0 Full Test Case Analysis (same as spec-forge:test-cases Steps 1-5)

Execute the **complete** spec-forge:test-cases analysis pipeline. The full workflow is defined in the spec-forge test-cases-generation skill (`spec-forge/skills/test-cases-generation/SKILL.md`). The essential steps are inlined below — follow them exactly:

**Step 1 — Determine Input Mode and Project Profile**
- Determine input mode: Scan / Code / Spec (from user arguments)
- Detect project profile: Web API / CLI Tool / Frontend App / AI Agent / Data Pipeline / Function Library / SDK
- Detect: has database? has auth? has external APIs?
- Output explicit profile with rationale

**Step 2 — Deep Scan and Extract (Four Layers)**
- Use the language-specific deep extraction strategy (Python / TypeScript / Go / Rust / Java)
- Extract ALL testable units across four layers:
  - **Interface**: public API surface, type contracts, trait/interface boundaries
  - **Logic**: branch paths, error chains, state transitions, validation rules
  - **Architecture**: module structure, layer boundaries, dependency direction
  - **Relationships**: call graphs, data flow, event propagation, trait implementations
- Scan existing tests to determine current coverage
- Run scan verification (file coverage ≥ 90%, module tree completeness, re-export tracking)
- Produce structured Functional Inventory with all four layers per unit

**Step 3 — Detect Dimensions**
- Apply built-in dimensions: Coverage Depth (L1/L2/L3)
- Auto-detect project-specific dimensions (Auth Context, Trigger Mode, Input Source, etc.)

**Step 4 — Confirm Scope with User**
- Present Profile confirmation: "I detected this as **{profile}** ({rationale}). Correct?"
- Present scope: "{N} testable units, {X} have tests, {Y} don't. Cover: all / uncovered / specific modules?"
- Present detected dimensions for confirmation
- Ask for business rules the code can't reveal

**Step 5 — Design Test Cases**
- Per testable unit, generate at minimum:
  - 1 × L1 (Happy Path)
  - 2 × L2 (Boundary + Error)
  - 1 × L3 (Negative — what should NOT happen)
- For interacting units: pairwise combination cases (L1 both succeed + L2 one fails + L3 should not combine)
- For auto-detected dimensions: cross with coverage depth using risk-based prioritization
- Apply conditional sections:
  - Data Integrity cases (only if project has database)
  - Security cases (only if project has auth or handles user input)
  - Performance cases (only if project has latency/throughput requirements)
- Assign priorities: P0 (critical path) / P1 (important) / P2 (nice-to-have)
- Build coverage matrix internally: unit × depth, dimension coverage, combination coverage, gap analysis

**Result**: A complete set of structured test cases in memory — identical quality to what spec-forge:test-cases would produce as a document.

### A.1 Optional: Save Test Cases Document

Ask the user: "Save the test cases as `docs/{feature}/test-cases.md` for future reference? (Y/n)"

- If yes → write the document following the spec-forge:test-cases template, then continue to A.2
- If no → keep in memory, continue to A.2

### A.2 Implement via TDD

For each test case (sorted by priority: P0 → P1 → P2), follow the same TDD cycle as Driven Mode:

1. **Read the case** — extract preconditions, steps, expected result, not-expected, test infra
2. **Set up test infrastructure** — if Test Infra is "Real DB", configure TestContainers; if "Mock external", set up mock; if "Temp dir", create temp directory; if "N/A", no setup
3. **RED** — Write a failing test matching the case specification
   - Test name should include TC ID: `test("TC-AUTH-001: create user with valid email returns 201", ...)`
   - Preconditions → test setup; Steps → test actions; Expected result → assertions; Not Expected → negative assertions
4. **VERIFY RED** — Run the test, confirm it fails correctly
5. **GREEN** — Write minimal production code to make it pass
6. **VERIFY GREEN** — Run all tests, confirm clean pass
7. **REFACTOR** — Clean up if needed
8. **Report** — "TC-AUTH-001: DONE"

### A.3 Progress Tracking

After each case, display progress (same format as Driven Mode D.4):
```
TDD Progress: {completed}/{total} ({percentage}%)
  [x] TC-AUTH-001: Create user with valid email (P0) — DONE
  [x] TC-AUTH-010: Duplicate email rejected (P0) — DONE
  [ ] TC-AUTH-011: Invalid email format (P1) — next
```

Ask: "Continue with next case, skip, or pause?"

### A.4 Completion

After all cases are implemented:
- Run full test suite
- Report: total cases implemented, all tests passing, coverage statistics
- If test cases were saved to file (A.1), report the file path
- Suggest: "Run `/code-forge:verify` to confirm completion"

## Standalone Mode — Classic TDD

For ad-hoc changes where the user describes what to build or fix:

### Workflow

```
RED (write failing test) → VERIFY RED → GREEN (minimal code) → VERIFY GREEN → REFACTOR → REPEAT
```

### The Cycle

Complete each phase fully before moving to the next.

#### 1. RED — Write a Failing Test

- One minimal test showing the desired behavior
- Clear, descriptive test name
- Use real code, not mocks (unless unavoidable: external APIs, time-dependent behavior)
- One behavior per test

#### 2. VERIFY RED — Watch It Fail (MANDATORY)

Run the test. Confirm:
- It **fails** (not errors)
- The failure message describes the missing behavior
- It fails because the feature is missing, not because of typos or setup issues

If the test **passes**: you're testing existing behavior. Rewrite the test.
If the test **errors**: fix the error, re-run until it fails correctly.

#### 3. GREEN — Write Minimal Code

- Simplest code that makes the test pass
- No extra features, no "while I'm here" improvements
- No premature abstractions — three similar lines beats a premature helper

#### 4. VERIFY GREEN — Watch It Pass (MANDATORY)

Run the test. Confirm:
- The new test **passes**
- All other tests **still pass**
- Output is clean (no warnings, no errors)

If the new test **fails**: fix the code, not the test.
If other tests **fail**: fix them now, before proceeding.

#### 5. REFACTOR — Clean Up (After Green Only)

- Remove duplication, improve names, extract helpers
- Keep all tests green throughout
- Do NOT add new behavior during refactor
- **Apply design-first here.** Look at the GREEN code in the context of the surrounding subsystem. Did GREEN push you toward a patch (new branch, new wrapper, parallel path) when a small refactor of the existing structure would have been cleaner? If so, refactor now while the test is green. The REFACTOR step is not optional — it is the moment design-first is enforced inside the TDD cycle. See `@../shared/design-first.md` for the discipline.

#### 6. REPEAT

Go back to Step 1 for the next behavior.

## Decision Rules

| If you're about to... | Instead... | Why |
|----------------------|-----------|-----|
| Write production code without a test | STOP — write the failing test first | Tests written after implementation pass immediately and prove nothing |
| Skip testing because the change is "simple" | Write the test — it will be quick if it's truly simple | Simple code has the sneakiest bugs (off-by-one, null edge cases) |
| Apply a quick fix without a regression test | Write the test, then fix | Untested fixes become permanent regressions |
| Continue with code that wasn't test-driven | Consider rewriting test-first | Sunk cost — untested code is a liability regardless of time spent |

## External Dependency Rules

**Principle: test your own dependencies for real; only mock what you don't control.**

| Your Dependency | Approach |
|----------------|----------|
| Own database | Real DB (TestContainers, test instance, SQLite in-memory) |
| Own file system | Real temp directory |
| Own cache / message queue | Real (TestContainers, embedded) |
| External third-party API | Mock / stub acceptable |
| Non-deterministic input (time, random) | Inject controlled values |

- For projects **without** a database or external I/O: most tests are pure unit tests — no special infra needed
- For write operations: verify state after the operation (DB query / file check / store assertion)

## Example

```
Task: Add isPalindrome(str) function

1. RED — Write test:
   test("isPalindrome returns true for 'racecar'", () => {
     expect(isPalindrome("racecar")).toBe(true);
   });

2. VERIFY RED — Run: npm test
   ✗ ReferenceError: isPalindrome is not defined    ← fails correctly

3. GREEN — Minimal code:
   function isPalindrome(str) {
     return str === str.split("").reverse().join("");
   }

4. VERIFY GREEN — Run: npm test
   ✓ isPalindrome returns true for 'racecar'        ← passes
   42 passed, 0 failed

5. REFACTOR — (no changes needed)

6. REPEAT — next test: edge case with empty string
```

**Test runner detection:** Check `package.json` scripts, `pytest.ini`, `Cargo.toml`, `go.mod`, or `Makefile` for the project's test command before starting the cycle. Use the same runner consistently.

## Verification Checklist

Before claiming work is complete:

- [ ] Every new function/method has at least one test
- [ ] Watched each test fail before implementing
- [ ] Each test failed for the expected reason (not errors)
- [ ] Wrote minimal code per test (no gold-plating)
- [ ] All tests pass with clean output
- [ ] Edge cases and error paths covered
- [ ] Mocks used only when unavoidable
- [ ] Database-touching tests use real database

## When Stuck

- Test too complicated to write → design is too complicated, simplify first
- Must mock everything → code is too coupled, extract interfaces
- Test setup is huge → extract test helpers or fixtures
- No test-cases document and unsure what to test → run `/spec-forge:test-cases` first to generate a structured case set