ia-debugging

• SKILL.mdcore · 7,298 bytes
• SKILL.mdcore · 7,298 bytes
• SKILL.mdcore · 7,298 bytes
• SPEC.mddoc · 4,698 bytes
• references/baseline-and-data-handling.mddoc · 2,423 bytes
• references/competing-hypotheses.mddoc · 3,946 bytes
• references/defense-in-depth.mddoc · 4,538 bytes
• references/repair-and-escalation.mddoc · 9,238 bytes
• references/reproduction-and-investigation.mddoc · 7,436 bytes
• references/root-cause-tracing.mddoc · 4,603 bytes
• references/specialized-patterns.mddoc · 17,727 bytes
• scripts/collect-diagnostics.shruns · 4,434 bytes

# 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](./references/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](./references/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.