systematic-debugging

name	systematic-debugging
description	Find root cause before fixing bugs, failing checks, build failures, performance issues, or unexpected runtime behavior. Use when symptoms need reproduction, diagnosis, or boundary tracing before repair. Use this skill for diagnosis only; it does not decide current-scope disposition, final architecture, or proof selection.

Systematic Debugging

Root cause first. No guess-fixing.

Iron Law

No fix before root-cause investigation. Build or identify a feedback loop before hypothesis-heavy debugging. The loop must reproduce the reported symptom or explain why reproduction is blocked.

Loop

1. Read the full error or symptom.
2. Reproduce or gather enough evidence to explain why reproduction is blocked.
3. Find the immediate cause, then trace backward through callers, data, state, config, and boundaries until the original trigger is known.
4. Compare with a working in-repo pattern.
5. State one hypothesis and test one variable.
6. Fix the source, not the symptom.
7. Add bounded guards or proof only where supported paths can still bypass the source fix.
8. Remove temporary debug instrumentation, probes, and throwaway harnesses unless a durable owner accepts them.
9. Verify the fix and surrounding checks.

For multi-component failures, record what enters and leaves each boundary until the failing layer is known.

Handoffs

• ../feedback-address/SKILL.md owns feedback disposition. Use this skill for diagnosis, not for deciding whether a verified issue is current-scope, separate debt, accepted temporary debt, or no change.
• After root cause is known, apply ../solution-shaping/SKILL.md for owner-correct repair.
• Read ../testing-best-practices/references/persistent-test-contract.md when tests rely on arbitrary sleeps or fixed waits.
• If the root cause is unresolved ownership, authority, contract, state, storage, or interface boundary, use ../solution-shaping/SKILL.md.
• If feedback caused the investigation, preserve its disposition when applying the fix or route.

Stop

• no symptom fix first
• no bundled cleanup during investigation
• no pretending to understand an unreproduced issue
• after three failed fixes, stop and reopen diagnosis

Reference Gate

• Read references/diagnostics.md when structured diagnostic evidence, correlation IDs, or bounded runtime context matters.