diagnosing-bugs

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

Updated May 31, 2026
One-click install
npx skills add https://github.com/AlexanderNarbaev/agi --skill diagnosing-bugs-alexandernarbaev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/AlexanderNarbaev/agi/tree/main/.opencode/skills/matt-pocock/diagnosing-bugs
Command: npx skills add https://github.com/AlexanderNarbaev/agi --skill diagnosing-bugs-alexandernarbaev

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 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: Ten ordered strategies for building a red-capable repro command, from failing tests and curl scripts to bisection harnesses, differential loops, and human-in-the-loop bash scripts. - Structured Hypothesis Testing: Generates 3-5 ranked, falsifiable hypotheses before testing, then instruments with tagged debug logs and one-variable-at-a-time probes. - Regression Lockdown: Turns the minimized repro into a regression test at a correct seam, verifies the fix against the original scenario, and removes all debug instrumentation. - Use Case: A user reports an intermittent export failure in production. The Skill guides building a deterministic replay loop from a captured request, minimizing the failing scenario, ranking hypotheses, and landing a fix with a regression test. ## Quick Start Ask the agent to diagnose the bug you are experiencing and describe the exact symptom, error message, or slowdown you observed.

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 sometimes?

For non-deterministic bugs, raise the reproduction rate instead of chasing a clean repro: loop the trigger 100 times, parallelize, add stress, and narrow timing windows. A 50% flake is debuggable; keep increasing the rate until your feedback loop reliably goes red.

How do I diagnose a performance regression in my code?

Establish a baseline measurement first using a timing harness, profiler, or query plan, then bisect between known-good and known-bad states. Logs are usually the wrong tool for perf work; measure first, fix second.

What should I do when I cannot reproduce a bug 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 should I write the regression test before the fix?

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

Can this debugging workflow handle bugs that need human interaction?

Yes, as a last resort it uses a human-in-the-loop bash script template that prompts the user through manual steps and captures their observations as structured output. The loop stays structured even when a human must click through the UI.