debug git:20261101.951d650A

Immutable. This exact content never changes and is served at /api/v1/blob/f6578a43c242e1f6.

---
name: debug
description: Find the cause of a bug, failing test, crash, unexpected behavior, or performance regression from reproducible evidence, and fix it when asked. Use when asked to debug or diagnose, or when /work routes a bug here.
---

# Debug with evidence

Find the cause of the reported failure, not a change that hides it. A request to
diagnose allows inspection only; a request to fix also allows a local fix and its
verification. When `/work` sent you here, stop at **Ready to fix** and return the
cause and the proposed fix: `/work` sizes it, and once the fix may proceed, its
build follows step 3 below. Never deploy, experiment on production, or replay
requests with real side effects without permission, and keep credentials out of
logs and shared output.

## 1. Reproduce

Record expected versus actual behavior, inputs, environment, and versions. Facts
only the reporter holds (what exactly they saw, when, who was affected, what they
already did about it) change the next check or the remedy: ask for them in one
message, at the latest with your diagnosis, and record the rest as unknown. Never
advise an action on the damage, such as a refund, without asking whether it was
already done. Then build the
smallest check that reaches the real failure: a test, a command, a request, or a
browser interaction that asserts the reported outcome. Record its output before
changing anything.

- **Intermittent:** count failures over attempts under controlled conditions
  (seed, time, ordering) instead of retrying until it passes.
- **Performance:** fix the metric and workload, and measure repeated baseline
  runs before profiling.
- **No reproduction:** reason from traces, logs, and code with explicitly
  provisional hypotheses, and ask for the smallest missing capture or access.

## 2. Find the cause

Trace the bad value or state across callers and boundaries, and compare a working
case with the failing one. For each plausible cause, state what it predicts and
run the cheapest check that could rule it out, changing one thing at a time.
Recent changes are leads, not proof; bisect only with a trustworthy good and bad
state, in a separate checkout. After a failed experiment, revise the explanation
before the next change. When checks stop teaching you anything, report what is
ruled out and the evidence still needed instead of stacking speculative patches.

**Ready to fix:** evidence connects the trigger, the faulty behavior, and the
symptom. A diagnosis-only request stops here with the cause and a proposed fix.

## 3. Fix and verify

1. Capture the failure in a regression test before the fix and watch it fail for
   the right reason. If no automated check is feasible, keep the reproducer and
   say so.
2. Make the smallest fix the evidence supports. Do not mask the failure with
   sleeps, broad catches, retries, or fallbacks.
3. Rerun the regression test, the original scenario, and the project's checks.
   Compare failure counts or measurements under the same conditions for
   intermittent and performance problems.
4. Remove your temporary probes.

Report the cause and its evidence, the fix, the checks run, and what remains
uncertain, distinguishing diagnosed, mitigated, and fixed-and-verified.