diagnosing-bugs

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Hard bugs and flaky performance regressions resist casual code reading; without a reproducible pass/fail signal, debugging devolves into guessing. This Skill enforces a disciplined six-phase diagnosis loop that builds a tight reproduction command before any hypothesis is tested. ## Core Features & Use Cases - Feedback Loop Construction: Builds a red-capable, deterministic, fast reproduction command using failing tests, curl scripts, CLI fixtures, Playwright browser scripts, trace replay, fuzz loops, or git bisect harnesses. - Ranked Hypothesis Testing: Generates 3-5 falsifiable hypotheses, instruments with tagged debug logs, and changes one variable at a time to isolate the root cause. - Regression Lockdown: Converts the minimized repro into a failing regression test at a correct seam, verifies the fix, and removes all instrumentation during cleanup. - Use Case: A user reports that an export endpoint intermittently throws a 500 error. The Skill drives creation of a curl-based loop that reproduces the failure, minimizes the input, tests ranked hypotheses, and lands a fix with a regression test. ## Quick Start Ask the agent to diagnose the failing export endpoint using the diagnosing-bugs skill and build a reproduction loop first.

Frequently Asked Questions about diagnosing-bugs

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

FAQPage Schema
How to reproduce a bug before fixing it?▼

Build a tight feedback loop first: a failing test, curl script, CLI invocation, or Playwright script that asserts the user's exact symptom. The loop must be deterministic, fast, and able to go red on this specific bug before any hypothesis work begins.

What tools can I use to build a bug reproduction loop?▼

Options include failing unit or e2e tests, curl/HTTP scripts against a dev server, CLI invocations with fixture inputs, headless browser scripts via Playwright or Puppeteer, captured trace replay, fuzz loops, and git bisect harnesses.

Can this debugging approach handle performance regressions?▼

Yes. For performance regressions, the Skill replaces log-based probing with measurement: establish a baseline using a timing harness, performance.now(), a profiler, or query plans, then bisect. Measure first, fix second.

What should I do when a bug cannot be reproduced locally?▼

Stop and say so explicitly rather than hypothesizing without a loop. Ask the user for environment access, a redacted captured artifact such as a HAR file or log dump, or permission to add temporary production instrumentation.

Why does the skill require writing the regression test before the fix?▼

Writing the test first confirms it actually catches the bug by watching it fail, then pass after the fix. If no correct test seam exists, that absence is itself a finding about the codebase architecture.