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.