Error in user YAML: (<unknown>): mapping values are not allowed in this context at line 2 column 76
---
name: debug
description: Diagnose and fix bugs or test failures using a scientific loop: reproduce, hypothesize, isolate variables, and apply a minimal root-cause fix.
---
Diagnose bugs, unexpected behavior, and failing tests systematically. Never guess-and-patch blindly.
- Record the exact input/steps, expected behavior, and actual behavior (including full error messages or stack traces).
- Build the smallest, fastest deterministic reproduction (e.g., a single targeted test or minimal command).
- If the bug cannot be reproduced yet, identify the missing state or environment factor before changing production code.
- Based on observations and code reading, list 2–3 plausible root causes.
- For each hypothesis, define the distinguishing test: what should we observe if it is true, and what evidence rules it out?
- Test one hypothesis at a time (inspect call chains, check actual runtime state, run targeted tests, or add temporary minimal probes).
- Keep track of ruled-out hypotheses and why they were eliminated so you do not loop in circles.
- If two consecutive experiments contradict your mental model, pause and challenge base assumptions (wrong branch, stale build/cache, ignored config, wrong process).
- Fix the underlying cause rather than papering over the symptom with defensive checks.
- Check whether the same module contains sibling instances violating the same invariant; fix proven sibling defects in the same module without expanding into unrelated areas.
- Remove all temporary debug logs or probes.
- Re-run the minimal reproduction from Step 1 to confirm the failure is gone.
- Add or update an automated test that fails before the fix and passes after.
- Run the relevant test suite and build/lint checks to verify no regressions.
- Symptom & Repro: Exact reproduction command or trigger.
- Root Cause: Verified explanation (
path:line) plus key ruled-out hypotheses. - Fix: Concise summary of the minimal change.
- Verification: Reproduction result + automated test/build output summary.