A bug survives several fixes
Replace repeated guesses with a feedback command that catches the exact reported failure.
Diagnosing Bugs by Matt Pocock
Use Diagnosing Bugs by Matt Pocock to investigate failures and performance regressions through a repeatable feedback loop. Reproduce the exact symptom, reduce the scenario, compare testable explanations, and verify a focused fix against both the minimized case and the original user flow.
Install and get started
Choose your agent to see how to get started. In Floatboat, copy a request that asks the agent to read the original instructions. Other options show the Skill installation command or the publisher’s native setup steps.
Choose an agent
Start in Floatboat
Copy the request into a Floatboat conversation
Read the original Diagnosing Bugs instructions at https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnosing-bugs/SKILL.md. Explain its purpose, required tools, and installation options, then help me use it.Let the agent read the original instructions and check how to use them in your environment.
Download Floatboat ↗Try this request
Use Diagnosing Bugs on the duplicate webhook issue. First build a repeatable signal for the duplicate charge, then investigate and verify the original scenario after fixing it.
About Diagnosing Bugs
Diagnosing Bugs is a debugging discipline in Matt Pocock’s engineering collection. It puts disproportionate effort into building a fast, repeatable pass-or-fail signal for the actual reported bug before developing theories. That signal may come from a test, HTTP request, CLI fixture, browser script, or another suitable harness. The workflow then minimizes the reproduction, ranks falsifiable hypotheses, adds targeted probes, and verifies a fix. Where a suitable testing seam exists, the reproduction becomes a regression test. The final cleanup removes temporary instrumentation and reruns the original scenario. Access to the failing environment and careful redaction of captured evidence remain important inputs.
Use Cases for Diagnosing Bugs
Explore bugs that keep returning, failures with unclear causes, or a slowdown after a change. Build evidence around the specific symptom and use the same feedback loop to compare hypotheses, so a successful command is not mistaken for a verified fix to the user’s problem.
An issue appears intermittently
Increase the reproduction rate with a controlled loop before choosing an explanation.
A release became slower
Build a comparable timing baseline and investigate the change against measured behavior.
How to Diagnose Bugs with a Feedback Loop
Give the agent the observed and expected behavior, environment, and reproduction inputs. Establish a reliable failing signal, minimize it, and test ranked explanations with targeted instrumentation. Apply a focused correction, rerun the original flow, and remove temporary probes before closing the task.
- 01
Build the failure signal
Describe the exact symptom and run a command that can detect it. Capture only the diagnostic evidence needed, with secrets removed.
- 02
Minimize and test explanations
Reduce inputs while preserving failure. Compare ranked hypotheses with probes that change one variable at a time.
- 03
Fix, verify, and clean up
Test the correction at an appropriate seam and rerun the original scenario. Remove debug instrumentation and record the supported cause.
Explore More Agent Skills
Read another Skill guide and check its original source before using it.
Diagnosing Bugs FAQ
Why build a loop before reading code for a theory?
The loop establishes whether the actual symptom can be detected repeatedly. Without it, plausible code explanations are difficult to disprove or use to verify a fix.
Must the signal be an automated unit test?
No. The source also describes HTTP scripts, CLI fixtures, browser checks, trace replay, and other harnesses. Choose a signal that reaches the real failure.
What if the bug is intermittent?
Use a controlled repeated trigger to raise the reproduction rate and preserve relevant timing or randomness. State the observed rate instead of presenting a single pass as certainty.
What if no reproducible signal is possible?
The documented workflow pauses diagnosis and identifies missing access or evidence. It asks for an appropriate environment, redacted artifact, or separately authorized instrumentation.
When should a regression test be added?
Add one before the fix when a real testing seam can exercise the observed bug pattern. If no suitable seam exists, report that architecture limitation rather than writing a misleading test.
What belongs in the completion report?
Include the supported cause, original reproduction result, regression verification if available, and confirmation that temporary probes were removed. Keep secret values out of evidence.