diagnosing-bugs
Diagnose a bug by writing ranked, falsifiable hypotheses before any code change, tagging temporary debug instrumentation for a zero-tolerance sweep, and gating the regression test to a red-then-green proof at the confirmed seam. Use when fixing a bug, debugging a failure, triaging an error, or the user asks to diagnose/root-cause/troubleshoot an issue.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- diagnosing-bugs
- description
- Diagnose a bug by writing ranked, falsifiable hypotheses before any code change, tagging temporary debug instrumentation for a zero-tolerance sweep, and gating the regression test to a red-then-green proof at the confirmed seam. Use when fixing a bug, debugging a failure, triaging an error, or the user asks to diagnose/root-cause/troubleshoot an issue.
03 SKILL.md 正文
diagnosing-bugs
Invariant
A bug fix must never begin with a code change: a ranked, falsifiable
hypothesis list — each entry stating its claim, its supporting evidence, and
the specific observation that would prove it false — must be written down
before any diagnostic or fix code is written. Any temporary debug
instrumentation added while testing those hypotheses must always carry one
fixed, consistent, grep-able tag and must NEVER ship untagged or unswept — a
grep -rn 'DBGRM:' <scope> sweep over the touched scope must return zero
lines before the fix is considered done. A fix must never land without a
regression test gated to the actual seam that broke, proven by a
red-on-pre-fix / green-on-post-fix check — not a coincidental higher-level
assertion that happens to pass.
Everything else in this procedure — the specific ranking heuristics, the minimization tactics, how the feedback loop gets tightened — is allowed to be approximate and adapted to the bug at hand.
These three checkpoints are never allowed to soften: hypothesis-before-code, tag-before-ship, seam-gated-test.
Where this comes from
The applied write-up this skill is sourced from is Matt Pocock's "How I
Diagnose Bugs" (aihero.dev, /skills-diagnosing-bugs) — the same corpus
tracer-bullets and its siblings in this marketplace were harvested from.
This skill is the applied, disciplined restatement of "guess and check" as an
actual procedure with falsifiability and auditability built in, rather than a
vibe.
When to use this
- Any time a bug is confirmed to exist and the next step is figuring out why, before writing a fix.
- Debugging a failure, triaging an error report, root-causing a flaky test, or investigating a regression.
- The moment the temptation is "let me just try changing this and see if it helps" — that is exactly the moment this skill exists to interrupt.
- Not for the moment a bug is first noticed or reported (that's triage/intake)
and not for designing new work from scratch (see
tracer-bulletsfor scoping unbuilt work) — this skill starts once a repro is in hand and a fix is the goal.
The procedure
Seven sequential steps, one source procedure. Every invocation needs all of them, in order — none is independently optional.
Step 0 — Tight feedback loop (prerequisite, not optional)
Before hypothesizing, confirm a fast, deterministic, sharp-signal repro exists: one command or test that reproduces the bug and reports pass/fail in seconds, with no flakiness.
Concrete check: can you run the repro twice in a row and get the same verdict in under ~10 seconds? If not, tighten the loop first — isolate the failing unit, stub slow externals, pin the failing input. If no such repro exists, building it is the first task. Do not proceed to Step 1 on a slow, manual, or flaky loop: every hypothesis test in the steps that follow inherits that loop's cost and noise, and a noisy loop makes falsification itself unreliable.
Step 1 — Ranked, falsifiable hypotheses, written BEFORE any code change
Before touching code — fix code or diagnostic code — write a numbered list. Each entry has three required parts:
- Claim — the specific mechanism believed broken. Not "something's wrong with auth," but "the token refresh fires before the old token is revoked, so both are briefly valid."
- Evidence so far — what's already been observed that makes this plausible.
- Falsifying test — the exact, cheap observation that would prove this claim FALSE. If you cannot state one, it is not a hypothesis — it is a vibe, and it does not go on the list.
Order the list by likelihood given the evidence (Occam's razor: prefer the explanation that covers all observed symptoms with the fewest assumptions); when two entries are close in likelihood, promote whichever is cheaper to falsify.
"I'll just try this and see" is never a valid Step 1. If code changed before this list existed, the list was skipped, not satisfied.
Step 2 — Test the top-ranked hypothesis using the tight loop
Run the falsifying test from the top of the ranked list. If it needs internal
visibility the loop doesn't already give you, add temporary debug
instrumentation (log/print/assert) — see the tagging rule in Step 6, applied
without exception, even for a single throwaway console.log.
Step 3 — Falsify or confirm, then move
- Falsified → cross it off with the observed evidence, move to the next ranked entry. Re-rank if the failed test surfaced new evidence — don't just fall through the original order blindly.
- Confirmed → proceed to Step 4.
Do not silently keep guessing outside the list. Every additional guess gets appended to the ranked list, with its own falsifying test, before it's tried.
Step 4 — Minimize to the load-bearing case
Once the mechanism is confirmed, strip the repro to the smallest input, state, or code path that still reproduces it. For each element — input field, config flag, code path, fixture — ask "does removing this still reproduce the bug?" Keep removing while the answer is yes. Stop when the remaining set is minimal.
That minimal set is both the sharpest possible feedback loop and the precise seam the fix and regression test in Step 5 must target.
Step 5 — Fix at the confirmed seam, then gate the regression test to it
Implement the fix. The regression test must exercise the exact boundary identified in Step 4 — not a coincidental higher-level test that happens to pass through that code path.
Deterministic proof it's gated correctly: check out the pre-fix state (stash the fix, or diff against the parent commit) and confirm the new test goes RED; reapply the fix and confirm it goes GREEN. A test that passes even without the fix is not gated to the real seam — go back to Step 4, the minimization wasn't tight enough. Skipping this red/green bracket is skipping the gate, not satisfying it loosely.
Step 6 — Zero-tolerance instrumentation sweep before shipping
Any code added purely to observe behavior during Steps 0–4 (not part of the
eventual fix) must be tagged with a single, fixed, greppable marker. The
default literal tag is DBGRM: (debug — remove), used as a
comment/log-message prefix regardless of language:
// DBGRM: ...# DBGRM: ...console.log('DBGRM:', ...)print(f"DBGRM: {x}")
Before the fix is considered done, run:
grep -rn 'DBGRM:' <scope>
over the touched scope. It MUST return zero lines. Anything still tagged is either deleted, or — in the rare case it's genuinely worth keeping as permanent observability — deliberately un-tagged and justified in the commit message. Never leave it tagged-and-shipped: a tagged-and-shipped instance means the sweep wasn't actually run.
Step 7 — Auditability
The ranked hypothesis list from Step 1, with which entries were falsified or confirmed and why, should be visible in the artifact that survives the task — PR description, commit message, or chat output. The point of ranking before testing is that someone else can audit the reasoning path afterward, not just trust the final diff.
Decision points, stated as concrete checks
Not "be careful" — a concrete check for each judgment call:
- Loop tight enough? → two consecutive runs, same verdict, under ~10 seconds. If not, fix the loop before Step 1.
- Is this actually a hypothesis? → can you name the observation that would prove it false? If not, it doesn't go on the list.
- Does this debug line need the
DBGRM:tag? → yes, always, no exceptions, if its only purpose is diagnostic observation. - Is the regression test gated correctly? → red on pre-fix checkout, green on post-fix. Skipping this bracket is skipping the gate, not satisfying it loosely.
Am I done?
All four, not a subset:
- A ranked hypothesis record exists and is visible (Step 1 + Step 7).
grep -rn 'DBGRM:' <scope>returns zero lines (Step 6).- A regression test exists, gated to the Step 4 seam, verified red-then-green (Step 5).
- The fix actually resolves the original tight-loop repro from Step 0.
04 同仓库更多 Skills
wayfinder
Chart a multi-session effort as a labeled map of typed decision tickets (grilling / prototype / research / task) with explicit dependencies and an open frontier agents self-assign into. Plans; never executes. Use this skill whenever the user is working with wayfinder, and on phrases like "chart this effort", "break this into tickets", "what's the frontier", "plan across sessions", or "map out the dependencies for this work".
wave-research
Staged, adversarial research that tries to break a thesis before believing it: waves, checkpoints, falsifiable sub-claims, rival hypotheses, an ACH matrix, source-incentive tags and a verified final thesis. Also carries Workflow templates for a one-pass research-and-verify fan-out. Use to stress-test or vet a contested claim; not for quick lookups.
second-opinion
Offer-only validation pipeline for a verdict or recommendation. Use when the user asks to validate, verify, fact-check, or get a second opinion on a claim or recommendation — "are you sure", "double-check this", "second opinion". Batches fact-checking against sources, adds scoped advisor personas for the angles that need judgment, then re-emits the response grouped into verified, flagged, and conflict, with a mandatory validation delta. Requires a subagent-spawning tool; without one it must decline rather than simulate.
machine-voice
Compression rules for standalone machine-read artifacts the reader scans — agent traces, tool-call logs, status lines, progress updates, handoff notes, state dumps, config, schemas, reference cards, and structured data another agent parses. Applies three layers: lexical compression, markdown structure as navigation, and emojis as typed status markers. Reach for it when emitting one of those artifacts on its own. Companion to human-voice, which governs prose a human reads and also owns any table or block that serves surrounding explanation. Neither skill applies to code or file contents the user will save, commit messages, creative writing, or turns that are only a clarifying question — those ship unstyled and uncompressed.
human-voice
Style for prose a human reads — answers, recommendations, explanations, research summaries, comparisons. Use on every conversational reply that contains prose for a person to read: triage intent, lead with the verdict, keep it scannable, tag claim confidence. Reach for it whenever answering a technical question, comparing options, or making a recommendation, even when the user says nothing about style. Companion to machine-voice, which instead governs standalone machine-read artifacts — agent traces, tool-call logs, status lines, progress updates, handoff notes, state dumps, config, schemas, reference cards, and structured data another agent parses. Neither skill applies to code or file contents, commit messages, creative writing, or turns that are only a clarifying question — those ship unstyled.
ai-writing-mistakes
Catch and repair the tells that mark prose as machine-written — the negation-flip ("it's not X, it's Y"), rule-of-three padding, hedge stacking, unearned intensifiers, filler verbs like delve and leverage, participle trailers ("...ensuring seamless integration"), sycophantic openers, empty closing summaries, and uniform em-dash/sentence rhythm. Use when drafting or revising any prose a human will read, including documents you were asked to author — READMEs, docs, PR bodies, release notes, emails — and when the user asks whether something "sounds like AI" or wants writing tightened. This is a wording pass, not a voice: human-voice still decides layout and confidence tags, machine-voice still owns traces and logs, and neither this skill nor those two touch code, commit messages, or quoted text.