diagnosing-bugs

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

Updated Nov 10, 2013
One-click install
npx skills add https://github.com/bnferguson/dotfiles --skill diagnosing-bugs-bnferguson
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/bnferguson/dotfiles/tree/main/.agents/skills/diagnosing-bugs
Command: npx skills add https://github.com/bnferguson/dotfiles --skill diagnosing-bugs-bnferguson

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Hard bugs and performance regressions resist casual debugging: staring at code rarely finds the cause, and untested hypotheses waste hours. This Skill enforces a disciplined six-phase diagnosis loop that builds a tight, red-capable feedback signal before any hypothesis is tested. ## Core Features & Use Cases - Feedback loop construction: Builds a fast, deterministic, agent-runnable repro command using failing tests, curl scripts, headless browsers, trace replay, fuzz loops, or bisection harnesses. - Ranked hypothesis testing: Generates 3-5 falsifiable hypotheses, then instruments with tagged debug logs or debugger breakpoints, changing one variable at a time. - Regression test and cleanup: Converts the minimized repro into a failing regression test at a correct seam, verifies the fix, and removes all tagged instrumentation. - Use Case: A user reports that an export endpoint intermittently returns stale data. The Skill builds a curl-based loop that reproduces the failure, minimizes the scenario, tests ranked hypotheses, and lands a fix with a regression test. ## Quick Start Ask the agent to diagnose the bug where the export endpoint intermittently returns stale data and follow the diagnosis loop.

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, parallelize, add stress, or inject sleeps. A 50%-flake bug is debuggable, so keep increasing the rate until the loop reliably goes red before forming hypotheses.

How to debug performance regressions systematically?▼

Establish a baseline measurement first using a timing harness, profiler, or query plan, then bisect to find the regression point. Logs are usually wrong for performance work; measure first and 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 instead of guessing.

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 as a finding.

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

Single-hypothesis generation anchors on the first plausible idea and wastes time. Generating 3-5 ranked, falsifiable hypotheses with stated predictions before testing any of them avoids anchoring and surfaces the real cause faster.