Tdd

---
description: >
  Test-driven implementation — execute the TDD plan from /eng.
  Requires /eng output as input. RED → GREEN → REFACTOR with checkpoint gates.
    /tdd            — execute TDD plan from /eng
    /tdd continue   — resume from last checkpoint
---

# TDD

Execute the implementation plan from `/eng` using strict test-driven development.
**No /eng output = no /tdd.** This skill requires a TDD Execution Order as input.

**This skill modifies code.**

---

## When to Use

| Signal | Action |
|--------|--------|
| `/eng` produced a TDD plan | `/tdd` — execute it |
| Implementation interrupted mid-cycle | `/tdd continue` — resume from last checkpoint |
| No `/eng` output exists | Stop. Run `/eng` first. |

---

## Output structure — Option A inverted pyramid (leaner, execution mode)

`/tdd` follows the **Inverted-Pyramid Output** pattern from
`skills/shared/formatting.md`, adapted for execution: the header is leaner
because /tdd is running an approved plan, not deciding the plan.

**Wizard flow** — one test cycle at a time. Never implement multiple tests
at once.

### Progress block

```
/tdd ═════════════════════════════════════════════════════════════════════════════════

  ▸ Phase 0  Validate Input
  ○ Phase 1  Branch Setup
  ○ Phase 2  RED → GREEN → REFACTOR
  ○ Phase 3  Suite Check
  ○ Phase 4  Handoff

══════════════════════════════════════════════════════════════════════════════════════
```

Markers update as phases progress: `▸` current · `✓` done · `○` pending.
Completed phases show a status note (e.g., `✓ 3 tests planned`,
`✓ cycle 2/3 GREEN`).

---

## Phase 0: Validate Input

Read the `/eng` output. Extract the TDD Execution Order.

**Required fields from /eng:**

| Field | What it contains |
|-------|-----------------|
| Test order | Numbered list of test files to create |
| Per test | What to verify (mapped to acceptance criteria) |
| Implementation order | What code to write after each test |

**If missing or incomplete:**

> **STOP.** The /eng output doesn't include a TDD plan.
> Run `/eng impl` first to generate the TDD Execution Order.

**Tracker integration** — run the Tracker Detection block from
`skills/shared/tracker.md` §Tracker Detection if `TRACKER_TYPE` is not yet
cached. Then run the §Issue Resolution Block to resolve `TASK_ISSUE` if not
already set. If `TRACKER_TYPE=github-issues` and `TASK_ISSUE` is resolved,
swap the issue's status label to `status:dev` using the §Status Swap Block.
This signals the task has entered implementation.

### Inverted-pyramid confirm — emit before any code

```
▎ ★ THE OVERVIEW
▎
▎ Executing {N} RED→GREEN→REFACTOR cycles from /eng output.
▎ {1-line scope: feature name + total files touched}

▎ ⚠ HEADLINE RISKS
▎
▎ • {e.g., "Branch is `main` — feature branch will be created"}
▎ • {e.g., "{N} existing tests cover affected paths — regression watch"}
▎ • {2–3 bullets max — surface the most material risks before the gate}

▎ ▸ FIRST CYCLE
▎
▎ Cycle 1/{N}: {test file} → {what it verifies — AC-N from /spec}

══════════════════════════════════════════════════════════════════════════════════════
  Receipts — Full Cycle Plan
══════════════════════════════════════════════════════════════════════════════════════

  1. {test file} → {what it verifies}
  2. {test file} → {what it verifies}
  ...

▎ ▸ GATE — proceed with cycle 1?                       {entry-point only}
▎
▎ Reply "go" to start (lean output).
▎ Reply "go verbose" for per-cycle receipts.
```

**When `/tdd` is downstream** (HANDOFF present, `Verbose: true` absent):
gate is suppressed. Test coverage depth follows P4 if `Principles:` is
present: essential → happy + error paths only; thorough → all edge cases;
exhaustive → every scenario. Without `Principles:`, use thorough (default).
Proceed directly to Phase 1 (branch setup) and run all cycles.
After all cycles complete, emit a transition line:

```
══ /tdd · {N}/{N} GREEN ✓ · {N} files created ══════════════════════════════════
```

**When `Verbose: true`:** confirm plan with user before writing any code.
Emit per-cycle receipts (checkpoint details).

---

## Phase 1: Branch Setup

Before writing any code, ensure you're on a feature branch:

```bash
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
  echo "⚠ ON PROTECTED BRANCH — creating feature branch"
  SLUG=$(echo "{feature-description}" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]')
  git checkout -b "feat/$SLUG"
fi
```

> **Never write code directly on main/master.**

---

## Phase 2: RED → GREEN → REFACTOR

Execute each test cycle from the TDD plan **one at a time, in order.**

### For each cycle:

#### Step 1: RED — Write the test

Write the test file as specified in the TDD plan.

**Rules:**
- Test must describe expected behavior, not implementation details
- Test must be runnable — no placeholders, no `skip`, no `todo`
- Test must target the acceptance criteria from `specs/{slug}.md` (whether
  `Source: product-authored` from /spec or `Source: engineering-inferred` from /eng)

**Run the test. It MUST fail.** If the test passes before any implementation
code, the test is wrong (testing existing behavior) or the feature already
exists — stop and investigate.

#### Step 2: GREEN — Write the implementation

Write the **minimum code** to make the test pass.

**Rules:**
- Smallest change that makes the test green
- No extra features, no "while I'm here" additions
- No premature abstractions — three similar lines > one premature helper
- Follow patterns from the codebase — read existing code first

**Run the test. It MUST pass.** If it fails, fix the implementation, not the test.

#### Step 3: REFACTOR — Clean up

Tests are green. Now improve the code without changing behavior.

**Rules:**
- Run tests after every refactor step — they must stay green
- Improve naming, extract methods only if genuinely needed
- Apply patterns from the existing codebase
- Do not add features during refactor

**Run tests again. Still green?** If any fail, undo and try again.

> **Cycle invariant:** RED must fail, GREEN must pass, REFACTOR must stay
> green. These are internal verification steps, not user-facing gates.
> The cycle checkpoint below is the only user-visible output per cycle.
> **Stop and ask the user only if:** RED passes unexpectedly, GREEN can't
> be made to pass after 2 attempts, or REFACTOR breaks tests.

### Cycle checkpoint

After each RED → GREEN → REFACTOR cycle, report:

```
CYCLE {N}/{total} COMPLETE
──────────────────────────────────────────────
  Test:    {test file}
  Verifies: {acceptance criteria}
  Status:  GREEN ✓
  Files:   {files created/modified}
──────────────────────────────────────────────
```

**If more cycles remain:** Proceed to next cycle.

**If user asked to pause:** Save state and report where to resume with `/tdd continue`.

### Checkpoint Persistence

After each cycle checkpoint, persist state to disk so `/tdd continue` can resume
after context compaction:

```bash
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
cat > ".tdd-checkpoint-${BRANCH}.json" << CKPT
{
  "branch": "$BRANCH",
  "total_cycles": {total},
  "completed": {N},
  "last_test": "{test file}",
  "last_status": "GREEN",
  "eng_plan_summary": "{one-line summary of remaining cycles}",
  "updated": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
CKPT
```

**On `/tdd continue`:** Read `.tdd-checkpoint-{branch}.json` first. If it exists,
use it to determine which cycle to resume from instead of re-parsing conversation context.

**On completion (Phase 3 pass):** Clean up: `rm -f ".tdd-checkpoint-${BRANCH}.json"`

---

## Phase 3: Suite Check

After all cycles are complete, run the **full test suite** — not just the new tests.

```bash
# Run whatever test command the project uses
npm test    # or pytest, dotnet test, etc.
```

**All tests must pass.** If existing tests break:
1. Read the failing test to understand what changed
2. Determine if the failure is expected (intentional behavior change) or a regression
3. If regression: fix the implementation, not the existing test
4. If intentional: update the existing test with user approval

**Output:**

```
SUITE CHECK
──────────────────────────────────────────────
  New tests:      {N} passing ✓
  Existing tests: {N} passing ✓
  Regressions:    {N} (0 = good)
──────────────────────────────────────────────
```

> **STOP if regressions > 0.** Do not proceed to handoff with broken tests.

---

## Phase 4: Handoff

### 4a · Task checkoff (if `/decompose` task)

If the `/eng` handoff included a `Task:` line (e.g., `Task: #3 in specs/auth.todos.md`),
mark that task complete in its TODOS file now that suite is green:

1. Read the TODOS file named in the `Task:` field.
2. Find the line matching `- [ ] ... #{N} ...` and change `[ ]` → `[x]`.
3. Also mark all AC sub-items `[x]` under that task.
4. Append `[tdd ✓]` to the task's badge line (continuation line below the task,
   indented 6 spaces). If `[eng ✓]` already exists on the badge line, append
   after it. If no badge line exists, create one. Skip if `[tdd ✓]` already present.
5. If the target is a per-spec file (`specs/{slug}.todos.md`), update the
   root `TODOS.md` index line for that slug: recalculate `{done}/{total} done`.
6. Stage the changed file(s).

**Skip this step when** the handoff has no `Task:` line (standalone `/eng`,
no `/decompose` context).

**Tracker badge label** — if `TRACKER_TYPE=github-issues` (see
`skills/shared/tracker.md` §Badge Label Block), also add the `hashb:tdd` label
to the GitHub Issue matching the task number. **Do NOT close the issue** — it
stays open for `/review`. Only `/ship` closes issues. Skip silently
on failure.

**Output** (one line, after the suite check block):

```
  Task:          #{N} marked [x] in {file} · {done}/{total} done
```

### 4b · Handoff summary

Summarize what was built and hand off to `/review`.

```
✓ TDD COMPLETE ─────────────────────────────────────────────────

  Feature       {feature name from /eng}
  Cycles        {N} RED → GREEN → REFACTOR
  Tests added   {N} — all passing
  Files created {list}
  Files modified {list}
  Suite status  ALL GREEN ✓
  Task          #{N} ✓ ({done}/{total} done)     ← only if Task: was in handoff

  Acceptance criteria coverage (from specs/{slug}.md):
    AC-1: {description} → {test file} ✓
    AC-2: {description} → {test file} ✓
    ...

  Next: /hashb:review (recommended — peer review){· /hashb:eng hold (if scope grew during implementation) · escalate (if regressions can't be resolved) — append only when flagged}

─────────────────────────────────────────────────────────────────
```

### Next Step

| Condition | Next Skill | Why |
|-----------|-----------|-----|
| All cycles complete, suite green | `/review` | Peer review before QA |
| Regressions found, can't resolve | Escalate to user | Need human judgment |
| Scope grew during implementation | `/eng hold` | Re-scope before continuing |

**Default chain behavior** (downstream, `Verbose: true` absent):
- Suite green → auto-invoke `/review`
- If `/review` returns CHANGES REQUESTED → fix and re-run affected cycles
- Max 2 review rounds, then escalate to user

---

## Rules

1. **Requires /eng input.** No TDD plan = no /tdd. Period.
2. **Inverted-pyramid output.** Phase 0 emits THE OVERVIEW / HEADLINE RISKS / FIRST CYCLE / GATE (interactive) or auto-proceeds (autonomous) before any code. Receipts (full cycle list) below the gate. See `skills/shared/formatting.md`.
3. **Plain English in prose.** Use the simplest words a working engineer would use mid-task. Keep technical precision for code identifiers, file paths, test framework terms, branch names. See `skills/shared/formatting.md`.
4. **One cycle at a time.** Never write multiple tests before implementing.
5. **RED must fail.** A test that passes on first run is suspicious.
6. **GREEN means minimum code.** Just enough to pass. Nothing extra.
7. **Refactor doesn't add features.** Only clean up what's there.
8. **Tests must stay green.** After every refactor, after every cycle.
9. **No placeholders.** Every test has real assertions. Every implementation is real code.
10. **Follow existing patterns.** Read the codebase before writing. Match what's there.
11. **Minimal diff per cycle.** Small commits, clear purpose.
12. **Full suite before handoff.** New tests passing isn't enough — everything must pass.
13. **Task checkoff on completion.** If a `Task:` line was in the handoff, mark it `[x]` in the TODOS file after suite passes. Update the root index count. This enables multi-session progress tracking without manual edits.