---
name: debugging
description: "Use when production failures, flaky tests, timeouts, swallowed errors, stale binaries, or unexpected results need root-cause investigation."
---

# debugging: evidence before the patch

## Contract

Follow `references/evidence-contract.md`. Debugging is bounded evidence work. A symptom or named caller does not define the
fault boundary. Preserve the failure and reproduce against the exact worktree,
binary, environment, and command. Process exit or model explanation is not fresh evidence.

## Root-cause loop

1. **Capture.** Record candidate commit, executable/dependency identity, target ABI aliases,
   declared host-runtime engines, environment, input fixture, command, exit status,
   stdout/stderr, and timestamp. A stale binary or cached result is a separate hypothesis.
2. **Reproduce.** Run the smallest deterministic reproducer twice when timing is involved. Keep
   the failing artifact. If it does not reproduce, classify it unresolved and narrow the
   environment; do not declare fixed.
3. **Trace.** Find every caller of the failing operation and follow data and error flow through
   wrappers, retries, timeouts, persistence, and process boundaries. Prefer the shared root
   boundary over a guard in only the caller named by the report.
4. **Hypothesize.** State one falsifiable hypothesis per boundary, including stale binary,
   input/environment drift, swallowed error, timeout race, and incorrect state. For each, name
   the command and observation that would falsify it. Run those probes before editing.
5. **Fix.** Change the smallest owned root cause. Do not increase a timeout as a substitute for
   understanding, catch and discard the error, delete or weaken the regression, or make a
   caller-only patch when shared behavior is the fault. An out-of-scope root cause is an
   amendment request.
6. **Regress.** Add or repair a deterministic test that fails for the original cause and passes
   after the fix on every affected supported target. Run it from the exact candidate. Pair
   judgment behavior with its eval and record the threshold and input digest.
7. **Report.** Record facts, hypotheses and falsification, root cause, changed paths, fresh gate
   status, unresolved questions, and review route in the evidence contract.

## Failure handling

A swallowed error remains a failure until its cause is preserved. A flaky result is unresolved
until a bounded reproducer or environment difference explains it. A changed binary,
dependency, fixture, or worktree invalidates old evidence. Stop on missing inputs, unbounded retry,
hidden failures, or a fix whose regression does not fail first.

## Inheritance and binding

Skill inheritance is explicit: `debugging` is an on-demand child of the `implementing` Coder
skill. It may load `context` for bounded memory and `verification` for fresh completion proof.
It is not a startup role skill and does not inherit `lane-execution`, `artifact-work`,
`reviewing`, `researching`, `planning`, or `sprint-graph`; it never dispatches or owns a lane.

Native loading binds the exact skill identifier and complete sorted bundle digest, including
regular-file path, mode, and bytes for `SKILL.md` and every accepted resource. A missing,
stale, replayed, cross-install, or role-mismatched bundle fails before investigation. The
result artifact binds the reproduction, task, candidate, and evidence digests.