diagnosing-bugs · git:20261102.bc6f8af · 2026-11-02 · sha256 e7786e1001714811
diagnosing-bugs git:20261102.bc6f8afA
Immutable. This exact content never changes and is served at /api/v1/blob/e7786e1001714811.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_eo534h47t2fq7gbv/e7786e10017148119a497c2eacf652d168acd35064d1a2bc87695706665e76d0.json
Then /plugin install diagnosing-bugs@markdownregistry-eo534h47t2fq7gbv in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: diagnosing-bugs description: Diagnoses bugs and performance regressions by building tight reproduction loops and falsifying root-cause hypotheses. Use when debugging failures, flaky tests, race conditions, or unexpected behavior. --- # Diagnosing Bugs Isolate and fix bugs systematically by building a deterministic reproduction loop first, falsifying competing hypotheses, and fixing the shared root cause across all callers. ## Decision tree 1. **Do you have a single command that reproduces the bug deterministically?** - **No** → Start at **Phase 1 (Build & Tighten the Feedback Loop)**. Do not edit production code yet. - **Yes** → Proceed to step 2. 2. **Have you proven the exact line and state transition where actual behavior diverges from the invariant?** - **No** → Execute **Phase 2 (Falsify Hypotheses)**. - **Yes** → Proceed to step 3. 3. **Have you checked every caller of the broken function across the codebase?** - **No** → Run `grep_search` to inspect all callers before applying the fix. - **Yes** → Execute **Phase 3 (Root-Cause Fix & Regression Lock)**. ## Debugging workflow ### Phase 1: Build & tighten the feedback loop - Construct a fast (<5s) command via `run_command` that turns **red** on this specific bug (unit/integration test at the closest seam, `curl`/CLI fixture, or `git bisect run` harness). - For intermittent or race-condition bugs, loop the trigger concurrently to raise the reproduction rate until it fails reliably. - Redact all secrets or credentials in captured logs as `<REDACTED>`. ### Phase 2: Falsify hypotheses - Trace data and execution flow backward from the symptom to the origin of the bad state. - Formulate 2–3 competing hypotheses and add minimal assertions or traces to falsify wrong ones. - If 3 consecutive hypotheses fail, remove **only** your temporary debug instrumentation via `replace_file_content` (or `git stash push -- <instrumented-files>`—never run `git checkout -- .` which would destroy the user's uncommitted work) and re-evaluate the architecture with the user. ### Phase 3: Root-cause fix & regression lock - Fix the shared root cause once in production code (never patch a single caller while leaving sibling callers broken). - **Anti-Test-Bypass Invariant**: The reproduction test is the behavioral oracle. The fix must be exclusively in production logic. Modifying, skipping (`.skip`), deleting, or weakening assertions in the test to artificially produce a green exit code is strictly prohibited. - Remove temporary debug traces, confirm the reproduction command turns **green** from the genuine production fix, and run the full test suite.