bug-diagnosis

Diagnose a bug systematically instead of guessing — reproduce, isolate, form hypotheses, and test them to root cause. Use when debugging, chasing a defect, an intermittent failure, or 'why is this happening?'. Produces a structured diagnosis: a reliable repro, the narrowed-down location, ranked hypotheses with how to test each, and the root cause + fix once found.

Published by mohitagw15856 ↗mohitagw15856/pm-claude-skills

Try your first task

bug-diagnosis

Start a fresh conversation. Replace the highlighted placeholders.

Use bug-diagnosis to investigate [bug symptom], using the supplied repro steps, environment context, recent changes, and prior attempts; establish a reliable reproduction before proposing a root-cause fix and regression test.

Required inputs

[bug symptom]

User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗

SKILL.md

name: bug-diagnosisdescription: "Diagnose a bug systematically instead of guessing — reproduce, isolate, form hypotheses, and test them to root cause. Use when debugging, chasing a defect, an intermittent failure, or 'why is this happening?'. Produces a structured diagnosis: a reliable repro, the narrowed-down location, ranked hypotheses with how to test each, and the root cause + fix once found."

Bug Diagnosis Skill

The slowest way to fix a bug is to start changing code and hope. This skill runs a disciplined diagnostic loop: reproduce it reliably, isolate where it happens, hypothesize why, and test the cheapest hypothesis first — narrowing until the root cause is proven, not guessed. It produces a fix and an explanation of why the bug existed.

Required Inputs

Ask for these only if they aren't already provided:

The symptom — what's wrong: expected vs. actual behavior, error/stack trace, when it started.
Repro steps — how to trigger it (or "can't reliably reproduce yet").
Context — recent changes, environment, frequency (always / intermittent / specific inputs).
What's been tried — so we don't repeat dead ends.

Output Format

Diagnosis: [bug]

1. Reproduce — the minimal, reliable steps to trigger it. If it's intermittent, the plan to make it deterministic (fixed input/seed, added logging, narrowed conditions). No fixing until it reproduces.

2. Isolate — narrow where it happens: bisect (git bisect / comment-out / binary search the input), check the boundaries (what's the last known-good point vs. first bad). State the smallest scope that still shows the bug.

3. Hypotheses (ranked) — likely causes, most-probable-and-cheapest-to-test first:

Hypothesis	Why plausible	How to test it (the cheap check)	Verdict

Test them in order; record what each rules in or out.

4. Root cause — the proven cause (not a symptom), with the evidence that confirms it.

5. Fix & guard — the fix, a test that fails before it and passes after (lock the bug out), and any nearby instances of the same mistake.

Quality Checks

A reliable reproduction exists before any fix is attempted
The location is isolated by bisection/narrowing, not guessed
Hypotheses are ranked by likelihood × cheapness and tested in order
The stated cause is the root cause with evidence — not just the surface symptom
A regression test is added that fails before the fix and passes after

Anti-Patterns

Do not start changing code before the bug reliably reproduces
Do not fix the symptom and stop — trace to the underlying cause
Do not change several things at once — you won't know what fixed it (or hid it)
Do not skip the regression test — an unguarded bug comes back
Do not ignore "what's been tried" — re-running dead ends wastes the loop

Based On

Systematic debugging method (reproduce → isolate → hypothesize → verify) — Zeller's Why Programs Fail / scientific-method debugging.

Example Trigger Phrases

"Help me debug this."
"Why is this happening?"
"This test fails intermittently."
"Find the root cause of this defect."