diagnosing bugs

Engineering Community

Skill notes

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 the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal. If the redacted output is not enough to diagnose the bug, say so and ask the user.

Phase 1: Build a feedback loop

This is the skill. Everything else is mechanical. If you have a tight pass/fail signal for the bug (one that goes red on this bug), you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you. Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.

Ways to construct one, in roughly this order

Failing test at whatever seam reaches the bug: unit, integration, e2e. Curl / HTTP script against a running dev server. CLI invocation with a fixture input, diffing stdout against a known-good snapshot. Headless browser script (Playwright / Puppeteer) that drives the UI and asserts on DOM/console/network. Replay a captured trace. Save a real network request / payload / event log to disk; replay it through the code path in isolation.

Tighten the loop

Treat the loop as a product. Once you have a loop, tighten it: Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.) Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".) Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.) A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight, a debugging superpower.

Non-deterministic bugs

The goal is not a clean repro but a higher reproduction rate. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not, so keep raising the rate until it's debuggable.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@mattpocock · no license declared
Token usage
Moderate
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
Windows
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Env read
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 1: Build a feedback loop

This is the skill. Everything else is mechanical. If you have a tight pass/fail signal for the bug (one that goes red on _this_ bug), you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you. Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.

02
Phase 2: Reproduce + minimise

Run the loop. Watch it go red as the bug appears. Confirm: [ ] The loop produces the failure mode the user described, not a different failure that happens to be nearby. Wrong bug = wrong fix. [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against). [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.

03
Phase 3: Hypothesise

Generate 3–5 ranked hypotheses before testing any of them. Single-hypothesis generation anchors on the first plausible idea.

04
Phase 4: Instrument

Each probe must map to a specific prediction from Phase 3. Change one variable at a time. Tool preference: Debugger / REPL inspection if the env supports it. One breakpoint beats ten logs. Targeted logs at the boundaries that distinguish hypotheses. Never "log everything and grep".

05
Phase 5: Fix + regression test

Write the regression test before the fix, but only if there is a correct seam for it. A correct seam is one where the test exercises the real bug pattern as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence. If no correct seam exists, that itself is the finding. Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.

06
Phase 6: Cleanup

Required before declaring done: [ ] Original repro no longer reproduces (re-run the Phase 1 loop) [ ] Regression test passes (or absence of seam is documented) [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix) [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.