agentleFS
ralfyishereralfyishere/rules-with-receipts/.claude/skills/debugging-playbook/SKILL.md

Debugging Playbook

Skill2 starsChanged 4 months agoMITView on GitHub

Debug systematically instead of guessing - symptom, reproduction, hypotheses, discriminating tests, evidence, root cause, fix, regression test. Activate whenever something is broken, failing, wrong, or behaving unexpectedly - error messages, failing tests, crashes, wrong output, performance regressions, "it worked yesterday", "why is this happening", intermittent issues. Also applies to non-code failures: a report with wrong numbers, a workflow producing bad results, a prompt giving bad outputs.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every hypothesis in the table reached a verdict backed by an observed result — no "probably" verdicts.

    line 56

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Debugging Playbook

Purpose

Replace guess-and-check with evidence-and-elimination. Unstructured debugging is a random walk: plausible fixes applied to unconfirmed causes, each failed attempt polluting the state for the next. The playbook's core rule: you have found the root cause when you can predict the system's behavior — before and after the fix — and be right.

When to use this skill

  • Anything broken, failing, or surprising: errors, test failures, wrong output, crashes, hangs, performance drops.
  • "It worked before" situations — these are diffing problems in disguise.
  • Non-code failures with the same shape: a spreadsheet total that's off, a pipeline producing bad rows, a prompt whose outputs degraded.
  • Intermittent problems — especially these; guessing is uniquely useless against nondeterminism.

When NOT to use this skill

  • The cause is already proven and trivial (the error message names the missing import). Fix it; ceremony adds nothing.
  • Nothing is broken — for "could this break?" work, use failure-mode-awareness.
  • Building new things — that's plan-gate/deep-decomposition territory, even if motivated by a bug.

Operating procedure

1 — Capture the symptom, verbatim. Full error text, exact command, exact input, environment. "Something about a timeout" is not a symptom. Note what correct behavior would look like — surprising numbers of debugging sessions chase behavior that was actually fine.

2 — Reproduce it. Find the smallest, fastest, most deterministic reproduction you can. Every minute invested here is repaid at every hypothesis test. If you cannot reproduce: don't guess-fix — instrument (logging, counters, capture-on-failure) and wait for the next occurrence, or hunt for the missing trigger condition (timing, data, environment).

  • For "worked yesterday": diff the worlds. What changed between then and now — code, data, dependencies, config, environment? git log / deploy history / dependency lockfile first.

3 — Generate 2–4 ranked hypotheses. Rank by likelihood × cheapness-to-test. Sources: the error itself (read all of it), the diff since it last worked, the failure catalogs in failure-mode-awareness, and where this class of bug usually lives.

4 — Design a discriminating test per hypothesis. A discriminating test has different predicted outcomes depending on whether the hypothesis is true — otherwise it's not a test, it's an activity. Prediction is written down before running.

5 — Run tests, cheapest-first, one variable at a time. Record results in the table:

#HypothesisDiscriminating testPrediction if trueResultVerdict
1Stale cache serves old configBypass cache with direct readDirect read returns correct valueCorrect value returnedSupported
2Config file itself is wrongcat the config on the affected hostFile shows the old valueFile shows new valueEliminated

Changing two things at once destroys the evidence — if the symptom moves, you can't say why. Revert each experiment before the next.

6 — Confirm root cause. The bar: your causal story explains all observed symptoms (including "why now" and "why only sometimes"), and you can toggle the bug — make it appear and disappear on demand via the cause. If evidence supports two stories, you're not done; find the discriminating test between them. Run adversarial-verify's "alternative explanation" attack here.

7 — Fix the cause, minimally. Smallest change that removes the cause — not a refactor of the neighborhood (see change-control and scope-fence). If you're fixing the symptom instead of the cause (sometimes legitimate under time pressure), say so explicitly.

8 — Add the regression test. The reproduction from step 2 is the test — it failed before the fix; it must pass after. Run the broader suite too: fixes are code changes, and code changes break things.

9 — Explain. Cause → why it produced these symptoms → why the fix addresses it → how it's verified. If the bug's lesson generalizes, log it via self-improvement-loop.

Quality bar

  • The root cause is demonstrated (toggleable, predictive), not just plausible.
  • Every hypothesis in the table reached a verdict backed by an observed result — no "probably" verdicts.
  • A regression test exists and was seen to fail-then-pass.

Common failure modes

  • Shotgun debugging: applying five plausible fixes at once. Even if the symptom vanishes, you've learned nothing and shipped four superstitions.
  • First-hypothesis anchoring: collecting only evidence that supports hypothesis #1. The table format exists to force alternatives.
  • Fixing the reproduction, not the bug: the minimal repro passes but the original scenario still fails — always re-verify against the original symptom.
  • Confusing correlation with cause: "it broke after the deploy" indicts the deploy's contents, pending evidence — not confirmed by timing alone.
  • Debugging the wrong layer: hours in application code when the discriminating test "does it fail on another machine?" would have pointed at environment in two minutes.
  • Abandoning the process under pressure: the playbook is faster than guessing precisely when the pressure is highest.

Example (compressed trace)

Symptom: "checkout intermittently charges customers twice" — captured verbatim with two affected order IDs. Repro: replayed one affected order's request log locally; double-charge appears when the payment webhook arrives twice. Hypotheses: (1) client double-submit, (2) webhook retry without idempotency, (3) race in order-status update. Discriminating tests: request logs show one client submission (eliminates 1); webhook log shows provider retry after a 6s timeout, and the handler has no idempotency key (supports 2); status race can't explain the 6s gap (weakens 3). Root cause confirmed: forcing a webhook timeout reproduces the double charge on demand; adding an idempotency key makes it vanish — toggleable. Fix: idempotency key on the charge call (minimal — no refactor of the handler). Regression test: replayed duplicate webhook now charges once; suite green. Explanation delivered with the "why only sometimes" answer: only slow responses trigger provider retries.

Works with sibling skills

  • live-state-truth is load-bearing throughout: verbatim errors, actual state, executed tests.
  • failure-mode-awareness catalogs are a hypothesis generator for step 3.
  • adversarial-verify gates step 6 (attack the diagnosis) and step 8 (attack the fix).
  • change-control governs the fix's blast radius; self-improvement-loop captures the reusable lesson.

Provenance and maintenance

Written 2026-07 as part of a portable, project-agnostic quality pack. No repo-specific claims. Re-verify against your own debugging history: for the last bug that took much longer than expected, identify which step was skipped (usually 2 or 4). If a step never earns its cost at your typical bug size, note the exemption here rather than silently skipping it.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.