diagnosing-bugs

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

7|1|Updated Jul 17, 2026
One-click install
npx skills add https://github.com/J0Jng/MathModelingAgents --skill diagnosing-bugs-j0jng
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/J0Jng/MathModelingAgents/tree/main/.claude/skills/engineering/diagnosing-bugs
Command: npx skills add https://github.com/J0Jng/MathModelingAgents --skill diagnosing-bugs-j0jng

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: Ten ranked strategies for building a tight pass/fail signal, from failing tests and curl scripts to headless browser runs, trace replay, fuzz loops, bisection harnesses, and differential comparisons. - Structured Six-Phase Workflow: Reproduce and minimize, generate 3-5 ranked falsifiable hypotheses, instrument with tagged debug logs, write regression tests at correct seams, and finish with cleanup and a post-mortem. - Non-Deterministic Bug Handling: Raise reproduction rates via repetition, parallelism, stress, and timing injection until flaky bugs become debuggable. - Use Case: A user reports an intermittent export failure in a web app. The Skill guides building a Playwright loop that reproduces the error, minimizing the scenario, testing ranked hypotheses one variable at a time, 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 reproducible failing test 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?▼

Non-deterministic bugs require raising the reproduction rate rather than finding a clean repro. Loop the trigger 100 times, parallelize, add stress, narrow timing windows, or inject sleeps until the failure rate is high enough to debug against.

How to diagnose a performance regression in code?▼

Performance regressions need measurement before fixing: establish a baseline with a timing harness, profiler, or query plan, then bisect between known states. Logging is usually the wrong tool for perf issues; measure first, fix second.

What should I do before forming a hypothesis about a bug?▼

Build a tight feedback loop first: one command that goes red on this specific bug, runs deterministically in seconds, and asserts the user's exact symptom. Jumping to hypotheses without a red-capable loop is the failure mode this workflow prevents.

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 a person through reproduction steps and captures their answers as structured output. The agent parses the captured values to continue the diagnosis.

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; the missing seam itself should be documented as an architectural finding.