Bug Hunter Skill

Most debugging sessions are unstructured. You change something, run it, see if it still breaks, repeat. This skill forces a different approach: state the hypothesis, test it, eliminate alternatives, find the actual cause. It is slower to start and much faster to finish.

What the skill does

• Failure path reconstruction. Traces the execution path from the trigger to the failure — what called what, what state was in memory, where the first wrong thing happened.
• Hypothesis generation. Produces a ranked list of likely causes based on the symptoms, the code, and the error output.
• Elimination protocol. For each hypothesis, identifies the cheapest test that would confirm or rule it out — no guessing, no changing three things at once.
• Root cause isolation. Distinguishes between the symptom (where the error surfaces) and the cause (where the logic first goes wrong).
• Fix proposal. Suggests a minimal, targeted fix that addresses the root cause without introducing new side effects.
• Regression test. Writes a test that would have caught this bug and will catch a recurrence.

How it works

1. Describe the bug. What is the expected behaviour? What actually happens? When did it start? Is it consistent or intermittent?
2. Share the relevant code. Paste the function, class, or module where the bug surfaces — and the caller if relevant.
3. Paste the error. Include the full stack trace, error message, and any relevant log output.
4. Hypothesis round. The skill generates a ranked list of hypotheses and the test for each.
5. Narrowing. You run the tests and report the results. The skill eliminates ruled-out hypotheses and refines the remaining ones.
6. Fix and verify. Once the root cause is confirmed, the skill produces the fix and a regression test.

How to use it

1. Click ⬇ Download this Claude Skill above.
2. Import through Claude Desktop (Customize → Skills → + → Create skill → Upload a skill) or drop into .claude/commands/. Full walkthrough in the import tutorial.
3. Invoke the skill:

   /bug-hunter
   

   Or open with full context:

   /bug-hunter Python 3.11, FastAPI. Users are getting 500 errors on the /checkout endpoint but only when they have more than 10 items in their cart. Worked fine last week.
   

---

Quick-start prompt (no download)

You are an expert debugger. Help me find the root cause of this bug using a structured approach.

Follow this process:

1. Reconstruct the failure path — trace execution from the trigger to the error.
2. List 3–5 hypotheses ranked by likelihood, based on the symptoms and code.
3. For each hypothesis, identify the minimum test that confirms or rules it out.
4. Once the root cause is identified, distinguish between the symptom location and the actual cause.
5. Propose a minimal fix that addresses the root cause specifically.
6. Write a regression test that would catch a recurrence.

Bug description: [what should happen vs. what actually happens, and when it started] Error message / stack trace: [paste here] Relevant code: [paste here] Language/framework: [specify]

Tips:

• "It worked before" is useful information — include the last known-good commit or deploy date if you have it.
• If the bug is intermittent, describe the pattern: under load? For specific users? At a specific time? That pattern is often the most important clue.
• Paste the full stack trace including the frames you think are irrelevant — those frames are often where the actual problem is.
• Ask the skill to write a minimal reproduction case if you cannot isolate the bug in your local environment.

⚠ This skill has been tested and optimized for Claude. Results may vary with other AI assistants.