diagnosing-bugs

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

Updated Aug 5, 2026
One-click install
npx skills add https://github.com/pd-phuc/laravel-template --skill diagnosing-bugs-pd-phuc
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/pd-phuc/laravel-template/tree/main/.claude/skills/diagnosing-bugs
Command: npx skills add https://github.com/pd-phuc/laravel-template --skill diagnosing-bugs-pd-phuc

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Hard bugs and flaky performance regressions resist casual code reading and single-hypothesis guessing. This Skill enforces a disciplined diagnosis loop that builds a tight, red-capable reproduction signal before any hypothesis is tested, preventing wasted hours of unfounded theorizing. ## Core Features & Use Cases - Feedback Loop Construction: Ten ranked strategies for building a pass/fail signal, from failing tests and curl scripts to property-based fuzzing, bisection harnesses, and human-in-the-loop bash scripts. - Structured Six-Phase Process: Build a loop, reproduce and minimize, generate 3-5 falsifiable ranked hypotheses, instrument with tagged debug logs, fix with a regression test, then clean up and post-mortem. - Non-Deterministic Bug Handling: Techniques to raise reproduction rates for flaky bugs through looping, parallelization, stress, and timing control. - Use Case: A user reports an intermittent export failure in production. The Skill guides the agent to build a replay harness from a captured request, minimize the failing scenario, rank hypotheses, instrument with tagged logs, and land 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 follow the diagnosis loop starting with a reproducible failing test.

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, and inject sleeps. A 50% flake rate is debuggable; keep increasing the rate until the failure is observable on demand.

How to reproduce a bug before fixing it?▼

Build a tight feedback loop first: a failing test, curl script, CLI invocation, or headless browser script that asserts the user's exact symptom. The loop must be deterministic, fast, and runnable unattended before any hypothesis testing begins.

What is the best way to debug performance regressions?▼

For performance regressions, avoid log-based debugging. Establish a baseline measurement with a timing harness, profiler, or query plan, then bisect between known-good and known-bad states. Measure first, fix second.

Why should I write a regression test before the fix?▼

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

When should I use a human-in-the-loop debugging script?▼

Use the hitl-loop.template.sh script only as a last resort when no automated loop is possible and a human must perform UI actions. The script structures the human's steps and captures their observations as parseable output for the agent.