---
name: debug
description: Use when a bug surfaces — failing test, segfault, wrong stdout, panic, or any observable misbehaviour. Bug fixes are RED-first TDD; no fix is attempted before the failing test exists in the working tree. Mandatory for any bug, including ones that look trivial.
---

# debug — RED-first bug diagnoser

> **Violating the letter of these rules is violating the spirit.**

## Overview

Bugs are diagnosed and fixed by a two-stage handoff: this
skill produces the RED test and the cause analysis; the
`implement` skill then drives the fix to GREEN. Skipping the
RED stage — even for "trivial" bugs — produces fixes that don't
stick and tests that don't exist to catch the next regression.

The substantive process — root cause investigation → pattern
analysis → minimal, autonomous RED test → handoff, plus the
Phase 4.5 architecture-question trigger after three failed
hypotheses — lives in `agents/debugger.md`. The RED stage is
not "any failing test": Phase 3 reduces the reproducer to the
smallest autonomous trigger before the test counts. That file is the single source of truth
for the discipline; this skill file only governs trigger,
dispatch, and handoff.

## When to Use / Skipping

Trigger this skill on:

- a failing run of the project's test command (its CLAUDE.md
  project facts)
- wrong stdout from running a project artefact
- a segfault from a built binary
- a panic / unhandled exception in the toolchain
- a structured diagnostic from `bencher` or `architect` that
  names a concrete misbehaviour

**Never skipped.** A bug without a regression test is a code
change, not a fix. Ad-hoc judgement that a bug is "too small
for TDD" is the exact failure mode this skill exists to prevent.

`debug` is for a regression of *existing* behaviour. New
test-specifiable behaviour is its sibling `tdd`'s job (same
two-stage RED→GREEN shape, triggered by a feature description
rather than an observed misbehaviour) — route there instead.

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
NO FIX WITHOUT A FAILING TEST FIRST
```

Both clauses are non-negotiable.

## Dispatch

Dispatch the `debugger` agent with the carrier fields it defines
under **Carrier contract** in `agents/debugger.md` — `symptom`,
`repro_known`, `recent_iter`. 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 fix —
splitting RED (this skill) and GREEN (`implement` mini-mode)
across two dispatches keeps the diagnosis honest. 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 will refuse the latter — so for an audit-trail-preserving
flow the orchestrator commits the RED test first; for a
streamlined-fix flow the orchestrator commits the combined
RED+GREEN at the end of mini-mode).

## Handoff Contract

`debug` produces, for `implement` mini-mode, the handoff carrier
the agent defines under **Output format** in `agents/debugger.md`
— `red_test_path`, `cause_summary`, `constraint`. That list is
the authoritative definition of those fields; it is deliberately
not restated here, so the two files cannot drift.

Anything else (broader refactor, doc rewrite, new feature) is
OUT of scope for the bug-fix iteration and gets queued for a
separate one.

## Cross-references

- **Agent dispatched:** `agents/debugger.md` — carries the
  four-phase process, the Phase 4.5 escalation rule, the
  Common Rationalisations table, and the Red Flags list. The
  orchestrator does not execute these phases directly.
- **Hand-off target:** `../implement/SKILL.md` — runs the
  GREEN side as the `implement-loop` workflow in `mode: "mini"`, after
  the orchestrator has decided whether to commit the RED test separately
  or as part of the final fix commit.
- **Sibling RED-first skill:** `../tdd/SKILL.md` — same
  two-stage RED→GREEN handoff to `implement` mini-mode, but
  triggered by a new test-specifiable behaviour rather than an
  observed bug.