Yolo Debug

---
name: yolo-debug
description: Use when a reported problem, failure, or bug needs a systematic root-cause investigation — reproduce → isolate → fix → verify — recorded as one durable artifact. Triggers on "fix the 500 on login", "X is broken", "why is Y failing?", "debug this", "track down this bug".
---

# yolo-debug

Find the *true cause* of a failure and fix it with evidence — not by guessing. A stateless
investigation act: it produces ONE debug record plus the fix, and stores no session state.

## Inputs
A bug report or failing behaviour. Derive a kebab-case `slug` for the record filename — there
is **no brief** (a debug is not a feature). Run on the **current branch** (see
`.claude/yolo/conventions.md` — a debug record never touches status derivation). If the work
turns out to add new capability rather than restore intended behaviour, **hand off to
`yolo-feature`**.

## Procedure
Work the arc in order; each step's output feeds the record.
1. **Reproduce** — get a deterministic repro (a failing test, a command, exact steps). No repro → no confirmed bug yet; say so rather than guessing.
2. **Hypothesize** — list candidate causes; rank by likelihood and cost-to-check.
3. **Isolate** — trace to the true cause with a concrete **evidence chain** (`file:line` → observed value → why it's wrong). Bisect or instrument as needed.
4. **Fix** — make the **minimal** change that addresses the root cause, not the symptom. Note the over-scope traps you avoided.
5. **Verify** — the failing reproducer now passes, the symptom is gone, and the wider suite stays green.

**The Iron Law:** no root-cause claim without a `file:line` evidence chain; no fix without a
failing reproducer that the fix flips to green; never patch the symptom while the cause stands.
Failing-test-first is the default — if a bug is genuinely not unit-testable (config, perf,
flake, environment), record *why* in the artifact and substitute the strongest available
evidence (a before/after command, a metric, a log excerpt).

## Discipline (the traps that end investigations early)
- "It's probably X" without checking is a guess, not a cause — confirm before you fix.
- The first plausible cause is not always the cause — confirm it explains the symptom *fully*.
- A green fix with no reproducer proves nothing — you may have moved the bug, not killed it.
- Red flags to stop and re-examine: the fix touches unrelated files; the bug "can't be reproduced but is fixed"; the explanation needs a "this should never happen".

## Output
Write exactly ONE artifact — `workspace/debug/<YYYY-MM-DD>-<slug>.md` (`mkdir -p` its dir) —
with: symptom + reproducer, the evidence chain (`file:line`), a one-sentence root cause +
confidence, the fix (files, the minimal change, over-scope avoided), and verification evidence.
Commit the record `yolo: debug <slug>`; the fix lands as ordinary descriptive commit(s) on the
current branch.

## Constraints
- Cite `.claude/yolo/conventions.md` for the commit form and the standalone-record rules; do
  not restate trailer strings. A debug record carries no trailer, no brief, no tracked state.
- Stateless: no persistent session or run-state files — the committed record plus the fix
  commit are the entire trail.
- Hand off to `yolo-feature` the moment the work becomes new capability rather than a fix.