diagnosing-bugs

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

Updated Sep 11, 2026
One-click install
npx skills add https://github.com/CYRUS-pinto/pi-bot --skill diagnosing-bugs-cyrus-pinto
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/CYRUS-pinto/pi-bot/tree/main/.agents/skills/diagnosing-bugs
Command: npx skills add https://github.com/CYRUS-pinto/pi-bot --skill diagnosing-bugs-cyrus-pinto

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 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 browsers, trace replay, fuzz loops, or bisection harnesses. - Ranked Hypothesis Testing: Generates 3-5 falsifiable hypotheses with explicit predictions, then instruments with tagged debug logs or debugger breakpoints, changing one variable at a time. - Regression Test Discipline: Writes the regression test before the fix at a correct seam, verifies the original repro no longer fails, and removes all tagged instrumentation during cleanup. - Use Case: A user reports that an export endpoint intermittently throws a 500 error. The Skill guides building a curl-based loop that reproduces the failure, minimizing the input payload, testing ranked 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 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 sometimes?

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

How to reproduce a bug before fixing it?

Build a tight feedback loop first: a failing test, curl script, CLI invocation with fixtures, headless browser script, or replayed captured trace 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 should I do when I cannot reproduce a bug locally?

Stop and say so explicitly rather than guessing. List what you tried, then 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 regression test first proves the test 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 itself is a finding about the codebase architecture worth flagging.

How do I debug a performance regression?

For performance regressions, avoid log-based probing. Establish a baseline measurement with a timing harness, profiler, or query plan, then bisect between known states to isolate the change. Measure first, fix second.