diagnosing-bugs

Diagnose hard bugs and performance regressions through a structured feedback-loop workflow.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/Fatih0234/mattpocock-skills-pi --skill diagnosing-bugs-fatih0234
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/Fatih0234/mattpocock-skills-pi/tree/main/skills/engineering/diagnosing-bugs
Command: npx skills add https://github.com/Fatih0234/mattpocock-skills-pi --skill diagnosing-bugs-fatih0234

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Hard bugs and performance regressions resist casual code reading; without a reproducible signal, debugging devolves into guessing. This Skill enforces a disciplined six-phase diagnosis loop that builds a tight, red-capable feedback loop before any hypothesis is tested. ## Core Features & Use Cases - Feedback Loop Construction: Builds a deterministic pass/fail signal via failing tests, curl scripts, CLI invocations, headless browser scripts, trace replay, fuzz loops, or bisection harnesses. - Structured Hypothesis Testing: Generates 3-5 ranked, falsifiable hypotheses, then instruments with tagged debug logs or debugger probes, changing one variable at a time. - Regression Lockdown: Writes a regression test at a correct seam before the fix, then cleans up all debug instrumentation and throwaway prototypes. - Use Case: A user reports an intermittent export failure in production. The Skill guides building a replay harness from a captured request, minimising the repro, ranking hypotheses, and landing a fix with a regression test. ## Quick Start Ask the agent to diagnose the bug where the export button throws an error, and have it build a failing reproduction loop before proposing any fix.

Frequently Asked Questions about diagnosing-bugs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose a bug that is hard to reproduce?▼

Build a feedback loop that raises the reproduction rate: loop the trigger 100 times, parallelise, add stress, narrow timing windows, or inject sleeps. A 50%-flake bug is debuggable; keep raising the rate until the loop reliably goes red.

How to debug a performance regression systematically?▼

Establish a baseline measurement first using a timing harness, performance.now(), a profiler, or a query plan, then bisect between known states. Logs are usually the wrong tool for performance work; measure first, fix second.

What should I do when I cannot build a reproduction loop?▼

Stop and say so explicitly, listing what you tried. Ask the user for environment access, a redacted captured artifact like a HAR file or log dump, or permission to add temporary production instrumentation before hypothesising.

When should I write a regression test for a bug fix?▼

Write the regression test before the fix, but only at a correct seam that exercises the real bug pattern as it occurs at the call site. If no correct seam exists, document that architectural gap instead of writing a shallow test.

Why does single-hypothesis debugging fail on hard bugs?▼

Single-hypothesis generation anchors on the first plausible idea and wastes cycles. Generate 3-5 ranked, falsifiable hypotheses with explicit predictions, show the list to the user for re-ranking, then test one variable at a time.