diagnosing-bugs
Diagnosis loop for hard bugs and performance regressions. Use when asked to diagnose or debug something, or when something is reported broken, throwing, failing, stuck, wrong or slow. Builds a fast, red-capable feedback loop before any theory, then reproduces, minimises, tests ranked hypotheses, fixes with a regression test and cleans up, with a redaction rule for secrets and personal data.
rknightion · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add rknightion/paperless-ngx-dedupe --skill diagnosing-bugsAbout this skill
name: diagnosing-bugs description: Diagnosis loop for hard bugs and performance regressions. Use when asked to diagnose or debug something, or when something is reported broken, throwing, failing, stuck, wrong or slow. Builds a fast, red-capable feedback loop before any theory, then reproduces, minimises, tests ranked hypotheses, fixes with a regression test and cleans up, with a redaction rule for secrets and personal data. license: MIT
Diagnosing bugs
Source: https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs
Changes from the source: the glossary and ADR pointers are replaced by the repository's AGENTS.md
and docs; the redaction rule covers personal data and real identifiers as well as secrets; added
where the loop may run; the human-in-the-loop script template is replaced by asking for one named
step; the red-first restore procedure lives in repo-conventions.
Inside the owner's agent loop, the repository's LOOP.md overrides this skill where they differ.
A discipline for hard bugs. Skip a phase only when you can say why.
Before exploring, read the repository's AGENTS.md and the docs for the area you are touching.
Redact
This skill has you show commands, outputs and captured artifacts. Redact every secret first: write
<REDACTED> in its place. Build loops against environment variables so the credential stays in the
environment and out of what you show. Captured requests carry auth headers: quote only the lines that
carry the signal.
Personal data, credentials and real identifiers (names, hostnames, IP addresses, account IDs, email addresses, serial numbers) follow the same rule. You may read them while diagnosing, but they never enter a committed file, fixture, test, doc, issue, pull request or commit message. A regression test built from a captured payload is rebuilt from a synthetic fixture of the same shape.
If the redacted output is not enough to diagnose the bug, say so and ask.
Where the loop may run
- Work in your own clone or worktree. Never touch a deployed environment, device or account you were not given. If the bug only shows there, ask a maintainer for a redacted capture, naming the exact read-only request or query you need.
- Build the loop from the narrowest command that reaches the bug (one test, one package, one
request), not from
just check. A loop that needs the full gate every run is not tight. - Run
justwith stdin from/dev/null, and bound every process you start with a timeout.
Phase 1: Build a feedback loop
Everything else depends on this. With a fast pass/fail signal that goes red on this bug, bisection, hypothesis testing and instrumentation all have something to consume. Without one, reading code will not find the cause. Spend most of your effort here.
Ways to construct one, roughly in this order
- A failing test at whatever seam reaches the bug: unit, integration, end to end.
- An HTTP request against a locally running server or a local Worker dev server.
- A CLI invocation with a fixture input, diffing stdout against a known-good snapshot.
- A headless browser script that drives the UI and asserts on DOM, console and network.
- A replayed capture: a sanitised request, payload or event log fed through the code path in isolation.
- A throwaway harness: a minimal subset of the system with fakes at the external edges.
- A property or fuzz loop when the bug is "sometimes wrong output".
- A bisection harness when the bug appeared between two known states: automate "build at state
X, check" and
git bisect runit. - A differential loop: old version against new, or two configs, diffing outputs.
- Ask the person for one step as a last resort, naming the exact action and the exact capture you need back.
Tighten the loop
Make it faster (cache setup, narrow the scope), sharper (assert the specific symptom, not "did not crash") and more deterministic (pin time, seed randomness, isolate the filesystem and database, fake the network). A 30-second flaky loop is barely better than none; a 2-second deterministic one finds the bug.
Non-deterministic bugs
Aim for a higher reproduction rate. Loop the trigger 100 times, run in parallel, add load, narrow timing windows. A 50% reproduction rate is debuggable; 1% is not.
When you cannot build a loop
Stop and say so. List what you tried and ask for one of: access to an environment that reproduces it, a redacted captured artifact, or permission to add temporary instrumentation. Do not hypothesise without a loop.
Done when
You can name one command you have already run (show it and its redacted output) that is:
- Red-capable: it drives the real bug path and asserts the reported symptom.
- Deterministic: the same verdict every run, or a pinned high reproduction rate.
- Fast: seconds, not minutes.
- Unattended: it runs without a person.
If you catch yourself building a theory from reading code before this command exists, stop.
Phase 2: Reproduce and minimise
Run the loop and watch it go red. Confirm it shows the failure that was reported, not a nearby one, and that it reproduces across runs. Capture the exact symptom (error, wrong output, timing).
Then shrink the repro 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. The minimal repro becomes the regression test in Phase 5.
Phase 3: Hypothesise
Write 3 to 5 ranked, falsifiable hypotheses before testing any. Format: "If X is the cause, then changing Y will make the bug disappear, or changing Z will make it worse." A hypothesis without a prediction is a guess: sharpen it or drop it. Show the ranked list to the person who asked when one is present; they may rule some out at once. Do not block on an answer.
Phase 4: Instrument
Each probe
Read the complete source ↗