debugging

Debugging

Ground permanent repairs in an evidence-backed causal explanation. A hypothesis may justify a bounded reversible experiment; label it as experimental until verified. During an active incident, an authorized rollback or feature disable may restore service before root cause is known. Record remaining uncertainty and keep the repair investigation open: mitigation is not proof of repair.

Scope and modes

For diagnosis-only requests, inspect source/artifacts and run safe read-only checks within caller authority; do not repair or violate a no-build constraint. Diagnosis may finish with an evidenced cause while its proposed repair remains unverified. Use NEEDS_CONTEXT only for information blocking the requested work.

Keep edits within the hypothesis's narrow file scope; revise the hypothesis before expanding it. Preserve other work. Before sharing diagnostics or searching externally, remove credentials, customer data, hostnames, IPs, paths, and SQL fragments as appropriate; use environment-sourced credentials rather than embedding secrets. Read baseline-and-data-handling.md for branch/build comparisons or diagnostic data sharing.

Process

1. Read and reproduce. Read the full error and totals, not just filtered matches. Confirm HEAD after session resumption before trusting carried file content. Run a provided reproducer before editing. Match the reported symptom exactly; a nearby failure is not the same reproduction. Use the cheapest actual trigger. For intermittent bugs, bound attempts and report conditions/frequency; a finite clean run does not disprove a race. Read reproduction-and-investigation.md when constructing, reducing, or instrumenting a reproducer.
2. Ground hypotheses. Form two to three candidates, each citing an observation. A trivial verified typo needs only a short causal check; an import error alone does not identify why import failed. Reduce irrelevant inputs while retaining the actual trigger. If no loop is available, report missing access, artifacts, credentials, or steps, and continue independent source investigation without claiming reproduction.
3. Trace and discriminate. Explain the violated invariant and triggering conditions, without imposing a fixed stack depth. Compare code, inputs, state, timing, environment, and build configuration. Identical source that passes another build can still contain undefined behavior or races. Use root-cause-tracing.md for backward tracing/test pollution and collect-diagnostics.sh for relevant environment captures. State the question and decision rule before probing; verify controls and build identity before trusting a result. Before repairing, list every observed symptom, including ones the reporter called unrelated; the cause must explain each, and an unexplained symptom means a second cause or an unfinished hypothesis (say which). When an observation contradicts a log or probe, suspect an uninstrumented path before discarding the observation.
4. Test one change. Test a named causal hypothesis with a minimal experiment. Revert a disproved experiment before the next; use bisect for an introduced regression when appropriate. A failed remedy can mean an incomplete fix or wrong build rather than a disproved cause. Reassess the actual evidence before another experiment. For competing multi-component explanations, read competing-hypotheses.md.
5. Repair and verify. For authorized fixes, read repair-and-escalation.md. Create a regression that exercises the real trigger: red without the fix, green with it. If no reachable test seam exists, report it instead of substituting a test that cannot fail for the reported defect. Verify the original entry point with fresh evidence under ia-verification-before-completion; do not weaken assertions, swallow failures, or special-case the exercised input. Run a bypass self-check with a nearby input reaching the same bad state; return to root cause if it bypasses the change. Security-relevant fixes need a fresh adversarial re-attack under specialized-patterns.md. Then sweep for the same defect shape: search the repo (skip generated/vendored code) for the fix's signature (call, missing guard, or lock omission) and classify each match as same bug, safe (why), or unsure. Fix a match only inside the hypothesis's file scope and with its own red/green check; list the rest or ask to widen scope. Trim the verified fix and remove diagnostic instrumentation.
6. Reassess after three failed cycles. Stop editing, reread the path, list failed assumptions, and escalate evidence. Three cycles are a retry budget, not proof of architectural failure. In diagnosis-only mode, three cycles without narrowing the component call for interim findings and the next instrumentation step. State an unknown cause honestly. Ask material missing questions through AskUserQuestion in Claude Code, request_user_input in Codex where supported, otherwise chat; unattended subagents return blockers to their parent.