diagnose

Files (1)

• SKILL.md

SKILL.md (first lines)

# diagnose

A discipline for hard bugs. Skip phases only when explicitly justified. Be scientific:
every shipped line traces to runtime evidence; the smallest change the evidence
justifies ships, nothing more ([fix-root-causes](../fix-root-causes/SKILL.md)).
Belt-and-suspenders that "might help" is a hypothesis, not a fix — when evidence refutes
a hypothesis, revert what it motivated.

When exploring the codebase, read `CONTEXT.md` (if it exists) for the domain vocabulary
and check ADRs in the area you're touching.

**Redact.** This skill has you show commands, outputs, and captured artifacts. Redact
every secret first: write `<REDACTED>` in its place, build loops against env vars so
credentials stay in the environment, and quote only the lines that carry the signal from
artifacts bearing auth headers.

## Phase 1: Build a feedback loop

**This is the skill.** Everything else is mechanical. With a **tight** pass/fail signal
that goes red on *this* bug, you will find the cause; bisection, hypothesis-testing, and
instrumentation all just consume it. Spend disproportionate effort here. Be aggressive.
Be creative. Refuse to give up.

Ways to construct one, in roughly this order: a failing test at whatever seam reaches
the bug; a curl/HTTP script against a dev server; a CLI invocation diffing stdout
against a known-good snapshot; a headless browser script asserting on DOM/console/
network; replaying a captured trace through the code path in isolation; a throwaway
harness (one service, mocked deps, single function call); a property/fuzz loop for
"sometimes wrong output"; a bisection harness (`git bisect run`) when the bug appeared
between two known states; a differential loop (same input through old vs new, diff the
outputs); and as a last resort a structured human-in-the-loop script whose captured
output feeds back to you.

**Tighten the loop.** Faster (cache setup, skip unrelated init, narrow scope), sharper
(assert the specific symptom, not "didn't crash"), more deterministic (pin time, seed
RNG, isolate filesystem, freeze network). A 2-second deterministic loop is a debugging
superpower. Non-deterministic bugs: raise the reproduction rate until debuggable — loop
the trigger 100×, parallelise, add stress, narrow timing windows.

**When you genuinely cannot build a loop**, stop and say so explicitly. List what you
tried; ask for environment access, a redacted captured artifact (HAR, log dump, core
dump, recording), or permission to add temporary instrumentation. Hypothesising without
a loop is the exact failure this skill prevents.

**Completion criterion:** one command you have already run at least once (show
invocation and redacted output) that is red-capable (asserts the user's exact symptom),
deterministic (or pinned high-rate), fast (seconds), and agent-runnable. No red-capable
command, no Phase 2.

## Phase 2: Reproduce + minimise

Run the loop; watch it go red. Confirm it produces the failure mode the *user*
described — a nearby different failure means wrong bug, wrong fix — and capture the
exact symptom for later verification. Then shrink to the **smallest scenario that still
goes red**: cut inputs, callers, config, data, and steps one at a time, re-running after
each cut. Done when every remaining element is load-bearing. Restart-flavoured bugs:
suspect stale persistent state (config, caches, locks, serialized state) before code.

## Phase 3: Hypothesise

Generate **3–5 ranked hypotheses** before testing any — single-hypothesis generation
anchors on the first plausible idea. Each must be falsifiable: "If X is the cause, then
changing Y makes the bug disappear / changing Z makes it worse." No stateable
prediction: discard or sharpen. Show the ranked list to the user before testing — they
often re-rank instantly — but proceed with your ranking if they're away. Confirm the
surviving *mechanism* with runtime evidence before designing the fix; a design grounded
on a plausible-but-unconfirmed cause can be confidently wrong while the real cause sits
one subsystem over.

## Phase 4: Instrument

Each probe maps to a specific Phase-3 prediction; change one variable at a time.
Debugger/REPL inspection first (one breakpoint beats ten logs), then targeted logs at
the boundaries that distinguish hypotheses. Tag every debug log with a unique prefix
(`[DEBUG-a4f2]`) so cleanup is one grep. For performance regressions, measure instead of
logging: baseline first (timing harness, profiler, query plan), then bisect.

## Phase 5: Fix + regression test

Write the regression test **before the fix**, at a **correct seam** — one where the test
exercises the real bug pattern as it occurs at the call site. A too-shallow seam gives
false confidence; **if no correct seam exists, that itself is the finding** — note it.
With a seam: turn the minimised repro into a failing test, watch it fail, apply the fix
(at the mechanism, where all callers route through; grep for the same pattern elsewhere
and fix all instances), watch it pass, then re-run the Phase-1 loop against the
original un-minimised scenario. Stage commits failing-repro-first, fix on top, so the
history tells the story
([sequence-verifiable-units](../sequence-verifiable-units/SKILL.md)).

## Phase 6: Cleanup

Before declaring done: original repro no longer reproduces (re-run the loop); regression
test passes (or the seam gap is documented); all `[DEBUG-...]` instrumentation removed
(grep the prefix); throwaway harnesses deleted or clearly marked; the winning hypothesis
stated in the commit/PR message so the next debugger learns. Working a bd ticket: close
it with the root cause and the verification evidence.

**Reply:** what was broken, root cause, fix, how you verified. Paste
failing-then-passing repro output verbatim (redacted).

From baranbingol1/bbstack, MIT.

More from baranbingol1/bbstack