diagnosing-bugs

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

Updated Jul 22, 2026
One-click install
npx skills add https://github.com/Chau165/local_skill --skill diagnosing-bugs-chau165
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/Chau165/local_skill/tree/main/codex/skills/diagnosing-bugs
Command: npx skills add https://github.com/Chau165/local_skill --skill diagnosing-bugs-chau165

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 tight, reproducible pass/fail signal, debugging devolves into guessing. This Skill enforces a disciplined diagnosis loop that builds a red-capable feedback command first, then reproduces, minimizes, hypothesizes, instruments, fixes, and cleans up. ## Core Features & Use Cases - Feedback Loop Construction: Builds a tight, deterministic, agent-runnable repro command using failing tests, curl scripts, CLI fixtures, headless browsers, trace replay, fuzz loops, or bisection harnesses. - Structured Hypothesis Testing: Generates 3-5 ranked, falsifiable hypotheses and maps each instrumentation probe to a specific prediction, changing one variable at a time. - Regression Test & Cleanup Discipline: Writes the regression test before the fix at a correct seam, tags debug logs with unique prefixes for grep-based removal, and ends with a post-mortem. - Use Case: A user reports an intermittent export failure in production. The Skill guides building a replay harness from a captured request, minimizing the failing scenario, testing ranked hypotheses with tagged logs, and landing a fix with a regression test. ## Quick Start Ask the agent to diagnose the bug where the export endpoint intermittently returns a 500 error, and have it build a reproducible feedback 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 I cannot reproduce consistently?

Non-deterministic bugs are handled by raising the reproduction rate rather than seeking a clean repro: loop the trigger 100 times, parallelize, add stress, narrow timing windows, and inject sleeps. A 50%-flake bug is debuggable; keep increasing the rate until it is.

What is a feedback loop in debugging and why build one first?

A feedback loop is a single tight command that goes red on the specific bug and green once fixed, such as a failing test, curl script, or replay harness. Building it first prevents premature hypothesizing, since bisection and instrumentation only work when they consume a reliable pass/fail signal.

How do I debug a performance regression instead of a crash?

For performance regressions, the Skill switches to a measurement branch: establish a baseline with a timing harness, performance.now(), a profiler, or a query plan, then bisect against that baseline. Logs are usually the wrong tool for perf issues; measure first, fix second.

What should I do when no environment can reproduce the bug?

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

When should a regression test not be written for a bug fix?

Skip the regression test when no correct seam exists, meaning no test location exercises the real bug pattern as it occurs at the call site. A shallow test gives false confidence; instead document the missing seam as an architectural finding.