---
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 (configured under
  `commands.test` in the profile)
- 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.

## 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. It is
  also the single source for the carrier and handoff field
  definitions (Carrier contract / Output format); this skill
  names the fields but does not redefine them. The orchestrator
  does not execute these phases directly.
- **Hand-off target:** `../implement/SKILL.md` — runs the
  GREEN side after the orchestrator has decided whether to
  commit the RED test separately or as part of the final fix
  commit.