systematic-debugginglisted

Root-cause-first debugging in four phases — investigate (read the full error, reproduce, check recent changes, instrument component boundaries), pattern-match against working examples, test one hypothesis at a time, then fix the cause with a failing test. Use when any bug, test failure, or unexpected behavior lacks a proven cause, when a fix is being proposed before the data flow was traced, when the previous fix didn't work, especially under time pressure (guessing is slower than the protocol), and when three or more fixes have failed — treat that as an architecture signal and raise it with the user instead of attempting a fourth. The bright line: no fix before the root cause is identified with evidence; in multi-component systems, log what enters and exits each boundary before theorizing. Hands the reproducing test to test-driven-development and the resolution claim to verification-before-completion. Not for changes whose cause is already proven (just fix them) and not for performance tuning without a defec
grimaldost/craft-collection · ★ 2 · Code & Development · score 68

Install: claude install-skill grimaldost/craft-collection

# Systematic Debugging Random fixes waste time and breed new bugs; symptom patches mask the cause until it resurfaces somewhere worse. The protocol: prove the cause, then fix it once. This is a **rigid** skill. The bright line: **no fix is proposed before the root cause is identified with evidence.** It holds hardest under time pressure — guess-and-check thrashes for hours where the four phases take minutes — and it applies to simple-looking bugs too, which have root causes like any other. ## Phase 1 — investigate 1. **Read the error completely.** The full stack trace, line numbers, error codes. The exact answer is often already in it. 2. **Reproduce reliably — observe before you theorize.** Exact steps, every time; not reproducible yet means gather more data, not guess. For a behavior or regression question, run the failing path and read its real output (logs, stack, emitted query) *before* forming hypotheses from source — dynamic observation precedes static theory. (Exception: when running the path is destructive, irreversible, or not yet buildable, read and instrument first — don't trigger a payment or drop a table to "observe" it.) And **confirm the code that ran is the code you read** — resolve the imported module's `__file__` and installed version; an editable checkout and an installed release of the same library diverge silently. (A data-engineering skill, when one is installed, states this canonically as an axiom — e.g. `data-en