Skill · Build
Debug with evidence
Debug methodically with AI: form hypotheses from the error and the code, rank them, and test each with evidence instead of guessing fixes.
The skill#
Act as a methodical senior engineer debugging a problem.
What should happen: [EXPECTED BEHAVIOR]
What happens instead: [ACTUAL BEHAVIOR]
Error message or logs: [PASTE ERROR OR LOGS]
Relevant code: [PASTE CODE]
What I have already tried: [WHAT YOU TRIED]
1. Restate the problem precisely.
2. List three to five hypotheses for the root cause, ranked by likelihood, each with your reasoning.
3. For each hypothesis, give one quick test that would confirm or rule it out.
4. Tell me which test to run first and what result to look for.
5. Only after a cause is confirmed, suggest the fix and how to verify it.
Do not jump to a fix before there is evidence for the cause. Do not invent library behavior; say when you are unsure.How to use it#
- Copy the skill and fill in expected versus actual behavior, the error and the relevant code.
- Run the first test it suggests and paste the result back into the chat.
- Repeat until one cause is confirmed, then apply the fix and the regression test.
Example#
A web form saves twice on slow connections. The skill ranks a double-click race condition first, suggests logging request IDs to test it, and only after you confirm proposes disabling the button and adding an idempotency key.
Quick and strict versions#
Use the quick version for everyday checks and the strict version when the result matters.
Here is my error and code. Give the three most likely causes, ranked, and the quickest test for each.
Error: [PASTE ERROR]
Code: [PASTE CODE]Act as a principal engineer running a root-cause investigation.
Symptoms, timeline and environment: [DETAILS]
Logs and errors: [PASTE LOGS]
Code and recent changes: [PASTE CODE OR DIFF]
1. Build a timeline of what changed before the bug appeared.
2. List hypotheses, ranked, with the evidence for and against each.
3. Design a minimal reproduction.
4. Give a test for each hypothesis that isolates one variable at a time.
5. After the cause is confirmed, propose the fix, a regression test and how to check nothing else broke.
6. Note whether the same cause could affect other parts of the system.
No fixes without a confirmed cause. Return: Timeline | Hypotheses | Reproduction | Tests | Fix planUse it as an agent skill#
Save this as SKILL.md in a folder named after the skill, and agents that support skills (Claude, Claude Code and other skill-aware agents) can load it automatically when the task fits.
---
name: debug-with-evidence
description: Use when the user has a bug, error message or unexpected behavior and wants help finding the root cause.
---
# Debug with evidence
Fill each [BRACKETED] field from the conversation. If one is missing, ask the user for it before starting.
Act as a methodical senior engineer debugging a problem.
What should happen: [EXPECTED BEHAVIOR]
What happens instead: [ACTUAL BEHAVIOR]
Error message or logs: [PASTE ERROR OR LOGS]
Relevant code: [PASTE CODE]
What I have already tried: [WHAT YOU TRIED]
1. Restate the problem precisely.
2. List three to five hypotheses for the root cause, ranked by likelihood, each with your reasoning.
3. For each hypothesis, give one quick test that would confirm or rule it out.
4. Tell me which test to run first and what result to look for.
5. Only after a cause is confirmed, suggest the fix and how to verify it.
Do not jump to a fix before there is evidence for the cause. Do not invent library behavior; say when you are unsure.
Frequently asked questions
Why not just ask the AI to fix the bug?
Guessed fixes often hide the symptom and leave the cause. Testing hypotheses finds the real cause and is usually faster overall.
What should I paste?
The exact error, the relevant code, what changed recently and what you already tried. More evidence means better hypotheses.
Does it work for non-code problems?
Yes. The same method works for broken spreadsheets, automations and device problems.