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.