---
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 in AILang 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
→ RED test → handoff, plus the Phase 4.5 architecture-question trigger
after three failed hypotheses — lives in
`agents/ailang-debugger.md`. 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 `cargo test` (any crate)
- wrong stdout from `ail run <example>`
- a segfault from a built binary
- a panic in the compiler
- a structured diagnostic from `ailang-bencher` or `ailang-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. The second was formerly the
CLAUDE.md "Bug fixes — TDD, always" section before the
2026-05-09 skill-system migration.

## Dispatch

Dispatch `ailang-debugger` with:

| Carrier field | Content |
|---------------|---------|
| `symptom` | Exact error message, stack trace, wrong output, or repro command |
| `repro_known` | One-line repro if known, otherwise the agent finds one |
| `recent_iter` | Iteration that last touched the suspected area (often `git log` tail) |

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 Boss 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 Boss commits the
RED test first; for a streamlined-fix flow the Boss commits the
combined RED+GREEN at the end of mini-mode).

## Handoff Contract

`debug` produces, for `implement` mini-mode:

| Field | Content |
|-------|---------|
| `red_test_path` | absolute path to the failing test file |
| `cause_summary` | 1-2 sentences naming the file + function + why |
| `constraint` | `"minimal fix, no surrounding cleanup"` |

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:** `skills/debug/agents/ailang-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:** `skills/implement/SKILL.md` — runs the GREEN
  side after the Boss has decided whether to commit the RED test
  separately or as part of the final fix commit.
- **Project source:** former CLAUDE.md "Bug fixes — TDD, always"
  section is now superseded by this file; CLAUDE.md keeps a one-line
  pointer.