debug · diff
git:20260630.95d2bc8 to git:20261006.60fda2b
105 added, 70 removed. Audit A to A.
---
name: debug
description: >-
- Debugs errors, test failures, and unexpected behavior with systematic root-cause
- analysis. Use when the user reports a bug, says "this isn't working", a test is
- failing, an exception is thrown, output is wrong, or asks to investigate "why does X
- happen". Applies to frontend, backend, database, network, and performance issues.
+ 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
- Trace the failure before changing code. Systematic root-cause analysis:
- reproduce, isolate, hypothesize, fix, verify.
+ 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.
- ## Process
+ ## 1. Establish the symptom safely
- 1. **Trace the failure** — capture the exact error, stack trace, failing command,
- and relevant logs. Done only when the failure can be quoted back verbatim.
- 2. **Reproduce reliably** — identify the smallest command or action that fails.
- Done only when it fails twice the same way, or is labeled intermittent with
- evidence.
- 3. **Gather evidence before hypothesis** — check recent changes, logs around the
- failure, expected environment, config, versions, and whether timing/races are
- plausible. Done only when each relevant item is recorded or ruled out.
- 4. **Isolate** — binary search via `git bisect`, comment blocks, feature flags,
- or a minimal repro. Done only when the failure is narrowed to a component,
- commit, input, or condition.
- 5. **Hypothesize** — state one specific theory and the observation that would
- disprove it. Do not change multiple things at once.
- 6. **Test hypothesis** — add temporary logging, use a debugger, or run a focused
- experiment. Done only when the result supports or rejects the theory.
- 7. **Apply minimal fix** — smallest change that addresses root cause, not symptoms.
- 8. **Verify** — rerun the original reproduction and relevant regression checks.
- Done only when the original failure no longer occurs and regressions are not
- detected or are explicitly reported.
+ 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.
- ## Evidence to Gather Before Hypothesis
+ Redact secrets before displaying or saving evidence:
- - Full error message, stack trace, and error code
- - Recent changes: `git log --oneline -10` / `git diff HEAD~1`
- - Logs around the time of failure
- - Environment: versions, env vars, config, external service state
- - Consistency: deterministic failure or intermittent pattern
+ - 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.
- **Reproduction:**
+ **Complete when:** the symptom and expected behavior are precise enough that the
+ final verification can distinguish fixed from unfixed without relying on judgment.
- ```bash
- # Find the commit that introduced it
- git bisect start
- git bisect bad HEAD
- git bisect good <last-known-good-sha>
- ```
+ ## 2. Build a tight red loop
- **Strategic logging:**
+ 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.
- ```typescript
- // Entry/exit with parameters — temporary, remove after fix
- console.log('[debug] functionName called', { param1, param2 });
- // ...
- console.log('[debug] functionName result', { result });
- ```
+ 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.
- ## Anti-Patterns
+ Run the loop at least once and show the invocation and redacted failing signal. A
+ tight loop is:
- - Don't make random changes hoping something fixes it — form a hypothesis first
- - Don't fix symptoms without understanding root cause
- - Don't debug in production without safeguards
- - Don't leave debug logs or breakpoints in committed code
- - Don't trust your mental model — read the actual code
+ - **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.
- ## Output
+ 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.
- ````markdown
- ## Root Cause
- [What actually caused the issue]
+ 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.
- ## Evidence
- - [Log excerpt / stack trace / variable state]
+ **Complete when:** one already-run command or action sequence is red-capable,
+ repeatable, and fast enough to guide diagnosis.
- ## Fix
- `file:line`
- ```diff
- - broken code
- + fixed code
- ```
+ ## 3. Reproduce and minimize
- **Why this fixes it:** [reasoning]
+ 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.
- ## Verification
- - [Command/repro rerun and result]
+ **Complete when:** the smallest practical scenario still produces the exact symptom,
+ and its invocation, inputs, conditions, and failure signal are recorded.
- ## Prevention
- - [Recommendation to avoid recurrence]
- ````
+ ## 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.