debug git:20261006.60fda2bA

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

---
name: debug
description: >-
  Debug errors, test failures, incorrect output, browser failures, intermittent bugs,
  and performance regressions through a tight red/green diagnosis loop. Use when
  behavior is broken, failing, flaky, slow, or unexplained.
---

# Debug

Build a **tight**, red-capable feedback loop before changing code. Then minimize,
test falsifiable hypotheses, fix the root cause, and drive the same loop green.

## 1. Establish the symptom safely

Capture the user's exact observable symptom: error, wrong output, UI state, failed
request, or measured latency. Record the triggering input, environment, and expected
versus actual behavior.

Redact secrets before displaying or saving evidence:

- Replace credentials, tokens, cookies, authorization headers, and personal data with
  `<REDACTED>`.
- Record environment-variable names and presence by default, not values.
- Keep credentials in the environment when building reproduction scripts.

**Complete when:** the symptom and expected behavior are precise enough that the
final verification can distinguish fixed from unfixed without relying on judgment.

## 2. Build a tight red loop

Create one command or agent-runnable action sequence that exercises the user's exact
symptom and returns an unambiguous pass/fail result. Prefer, in order, an existing
failing test, a focused test, an HTTP or CLI script, a browser automation flow, or a
replay of captured input.

For browser-visible or interaction bugs, invoke the installed `agent-browser` skill.
Use it to drive the reproduction and capture relevant DOM state, console or page
errors, network evidence, screenshots, traces, or video. Keep authentication
human-controlled or in its auth vault.

Run the loop at least once and show the invocation and redacted failing signal. A
tight loop is:

- **Red-capable:** fails on the user's exact symptom, not a nearby error.
- **Deterministic:** returns the same verdict, or a measured and pinned failure rate.
- **Fast:** cheap enough to run after every experiment.
- **Agent-runnable:** runs unattended whenever automation can reach the behavior.

For intermittent bugs, measure a baseline failure rate and raise it through repeated
runs, controlled timing, concurrency, load, or replayed input. Record the conditions
and sample size so the same experiment can be repeated after the fix.

If no useful loop can be built, stop and list what was tried. Request the missing
environment access, a redacted HAR/log/trace/recording, or permission for temporary
production instrumentation. Use a structured human-driven loop only when automation
cannot perform an irreducibly human action such as 2FA, biometrics, or physical-device
interaction.

**Complete when:** one already-run command or action sequence is red-capable,
repeatable, and fast enough to guide diagnosis.

## 3. Reproduce and minimize

Run the loop until the failure is understood at the observable level. Shrink inputs,
steps, config, data, and dependencies one at a time; rerun after every cut and retain
only what keeps the loop red. For intermittent bugs, preserve the pinned conditions
and report the measured failure rate rather than claiming determinism.

**Complete when:** the smallest practical scenario still produces the exact symptom,
and its invocation, inputs, conditions, and failure signal are recorded.

## 4. Rank falsifiable hypotheses

Generate 3–5 plausible root-cause hypotheses before testing any one of them. For each,
record:

- supporting evidence;
- contradicting or missing evidence;
- the observation predicted if it is true;
- the cheapest experiment that distinguishes it from the alternatives.

Rank by explanatory power and test cost. Discard or sharpen any hypothesis that makes
no falsifiable prediction.

**Complete when:** the hypotheses are ranked and the next experiment has a predicted
result that can support or reject one or more of them.

## 5. Run one-variable experiments

Change one variable at a time and map every probe to a prediction from Phase 4. Use
focused logging, a debugger, config or input substitution, dependency isolation, or
history comparison as the hypothesis requires. Inspect recent changes, versions,
configuration, service state, and timing only when they distinguish live hypotheses.

Use `git bisect` only with a known-good revision and the red/green loop as its test;
restore the original repository state with `git bisect reset` afterward. Keep
instrumentation temporary and redact its output.

After each experiment, record the command, result, and which hypotheses gained or
lost support. Update the ranking before choosing the next experiment.

**Complete when:** evidence identifies the causal mechanism and explains the observed
symptom; correlation or a disappearing symptom alone is insufficient.

## 6. Prove, fix, and clean up

When a stable test seam exists, add a regression test before the fix and run it red on
the reported symptom. Otherwise, state why the reproduction loop is the appropriate
verification artifact. Apply the smallest change that addresses the causal mechanism.

Run the regression test or original loop green. For intermittent bugs, use the same
conditions and sample size as the baseline. Run the relevant broader checks, then
remove temporary logs, flags, fixtures, recordings, breakpoints, and instrumentation.

**Complete when:** the original symptom is green, the regression checks pass or their
failures are reported, temporary debugging artifacts are removed, and the evidence
connects the fix to the root cause.

## Report

Return:

- **Root cause:** causal mechanism and affected path.
- **Evidence:** decisive observations and falsified alternatives.
- **Fix:** changed files and why the change addresses the cause.
- **Verification:** red-to-green loop and broader checks with results.
- **Remaining risk:** unresolved uncertainty or unsupported environments, if any.
- **Prevention:** only when a concrete preventive change follows from the evidence.