1---2name: debugging-methodology3description: >-4 Debugs failures by gathering evidence before proposing fixes, enforcing no fix5 without root-cause investigation. Use this skill when encountering bugs, test6 failures, unexpected behavior, intermittents, or works-locally-fails-in-CI,7 before changing code. Do not use when/for implementing a feature with no8 failure under investigation, or pure code-flow-analysis without a live9 failure.10version: 1.3.011---1213# Debugging Methodology1415## Critical rules1617- `NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST`. No evidence → no fix proposal.18- Measure; do not speculate. Instrumentation before hypothesis.19- One change at a time. Never stack unverified fixes.20- 3+ failed fixes → stop, question architecture, discuss before more attempts.21- Red flags: "quick fix now", "try changing X", multi-change batches, "probably X", proposing solutions before data flow is traced.22- Before instrumenting, map the path with `code-flow-analysis`. Before deep examples, read [references/protocol.md](references/protocol.md).2324## Workflow25261. Document the exact symptom (error text, expected vs actual, inputs, environment).272. Add instrumentation at decision points before forming any hypothesis.283. For complex flows, use OpenTelemetry spans (or existing production traces).294. Form a testable, evidence-based hypothesis that explains all symptoms.305. Apply one change; retest; keep structured logging, remove debug-only noise.316. For `Result` / workflow failures: log every `err()`, each step, and mock interactions. See protocol for patterns.3233## Resources3435- [references/protocol.md](references/protocol.md) — instrumentation, Result/workflow debugging, decision tree, anti-patterns, rationalizations. Read before instrumenting or when stuck.3637## Validation3839- [ ] Exact symptom captured40- [ ] Instrumentation evidence explains the failure (not a guess)41- [ ] Hypothesis confirmed with a single isolating change42- [ ] Root cause identified (not only symptom location)43- [ ] Regression test fails without fix, passes with it44- [ ] Original failure no longer reproduces; suite/build green45- [ ] Debug-level noise removed; structured logs/traces kept4647## Constraints4849- Skip the full protocol only for trivial self-evident issues the compiler already names (typo, missing import).50- Related: `code-flow-analysis`, `investigation-modes`, `result-types`, `fn-args-deps`, `verification-before-completion`, `confidence-levels`, `observability`.
jagreehal