diagnosing-bugs

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

Updated May 11, 2026
One-click install
npx skills add https://github.com/cloudofgeorge/AI-hands-Engineer --skill diagnosing-bugs-cloudofgeorge
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/cloudofgeorge/AI-hands-Engineer/tree/main/skills/engineering/diagnosing-bugs
Command: npx skills add https://github.com/cloudofgeorge/AI-hands-Engineer --skill diagnosing-bugs-cloudofgeorge

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Hard bugs and performance regressions stall when developers jump straight to hypotheses without a reproducible signal. This Skill enforces a disciplined diagnosis loop that builds a tight pass/fail feedback signal first, then reproduces, minimizes, hypothesizes, instruments, fixes, and cleans up. ## Core Features & Use Cases - Feedback loop construction: Builds a red-capable, deterministic, fast reproduction command using failing tests, curl scripts, CLI fixtures, headless browser scripts, trace replays, fuzz loops, or bisection harnesses. - Structured hypothesis testing: Generates 3-5 ranked falsifiable hypotheses, then instruments with tagged debug logs or debugger breakpoints, changing one variable at a time. - Regression testing and post-mortem: Writes the regression test before the fix at a correct seam, removes all debug instrumentation, and documents the confirmed root cause. - Use Case: A user reports that an export endpoint intermittently returns corrupted data. The Skill guides building a loop that replays the failing request 100 times, minimizes the repro, tests ranked hypotheses, and lands a fix with a regression test. ## Quick Start Diagnose this bug: the export endpoint intermittently returns corrupted JSON, and build a 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 debug a bug that only happens intermittently?

Intermittent bugs require raising the reproduction rate rather than finding a clean repro. Loop the trigger 100 times, parallelize execution, add stress, and narrow timing windows until the failure rate is high enough to debug against.

How to reproduce a bug before fixing it?

Build a feedback loop first: a failing test, curl script, CLI invocation, or headless browser script that goes red on the exact symptom. Then minimize the repro by removing inputs and steps one at a time until every remaining element is load-bearing.

What is the best way to debug performance regressions?

Performance regressions need measurement before logging. Establish a baseline with a timing harness, profiler, or query plan, then bisect between known states to isolate the change that introduced the slowdown.

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

Write the regression test before the fix, but only at a correct seam where the test 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 debugging fail when jumping straight to a hypothesis?

Hypothesizing without a red-capable reproduction command anchors on the first plausible idea and cannot verify fixes. A tight deterministic loop that asserts the user's exact symptom is required before generating ranked falsifiable hypotheses.