Root-cause debugging
Debugs a bug by reproducing it first, isolating it, testing one hypothesis at a time with evidence, fixing the cause instead of the symptom and adding a regression test. Use when something fails, crashes or behaves unexpectedly.
root-cause-debuggingInstall
Run one command — it saves SKILL.md into your agent's skills folder. Restart the agent and the skill is picked up automatically.
mkdir -p ~/.claude/skills/root-cause-debugging && curl -fsSL https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md -o ~/.claude/skills/root-cause-debugging/SKILL.md
mkdir -p ~/.agents/skills/root-cause-debugging && curl -fsSL https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md -o ~/.agents/skills/root-cause-debugging/SKILL.md
New-Item -ItemType Directory -Force "$HOME\.claude\skills\root-cause-debugging" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md -UseBasicParsing -OutFile "$HOME\.claude\skills\root-cause-debugging\SKILL.md"
New-Item -ItemType Directory -Force "$HOME\.agents\skills\root-cause-debugging" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md -UseBasicParsing -OutFile "$HOME\.agents\skills\root-cause-debugging\SKILL.md"
Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md
SKILL.md
Root-Cause Debugging
Your job is to find why the bug happens, not to make the error message go away. Do not edit code to "see if it helps" before you can explain the failure.
Workflow
1. Reproduce
- Get the exact failing input, command, request or test. Copy the real error text.
- Run it yourself and watch it fail. If you cannot reproduce it, say so and gather more data (versions, environment, logs, config) instead of guessing.
- Reduce the reproduction to the shortest form: one command or one failing test.
- Note whether it fails every time or sometimes. A sometimes-failure is a different problem (timing, shared state, data); record the failure rate over several runs.
2. Read before you change
- Read the full stack trace from the bottom frame that belongs to the project, not only the top line.
- Read the code on the failing path end to end, including the callers that produce the bad value.
- Check what changed recently:
git log -p -n 5 -- <file>, dependency bumps, config or environment changes.
3. Isolate
Narrow the search space with cheap experiments:
- Cut the input down until removing anything more makes the bug disappear.
- Bypass layers (call the function directly, skip the cache, use a stub for the network) to find which layer owns the fault.
- Compare a working case with a failing one and list every difference.
- Add temporary logging or assertions at layer boundaries to see where the data first becomes wrong. Remove them afterwards.
4. Hypothesis, one at a time
- State one hypothesis in a sentence: "The total is wrong because
discountis applied twice when the cart has a coupon." - Decide what observation would prove it wrong. Run that check first.
- Change one thing per experiment. If you change two things and it works, you do not know which one mattered.
- Write down rejected hypotheses so you do not test them twice.
5. Confirm the cause
You have the cause only when you can answer: why does the bad value appear, where does it originate, and why does the working case not hit it. Show the evidence (a printed value, a failing assertion, a trace line), not a feeling.
6. Fix the cause
- Fix at the place where the wrong thing is introduced, not where it is noticed. Catching an exception or adding a null check downstream is usually a symptom patch.
- Check for the same defect elsewhere:
grepfor the same call pattern or helper. - Keep the fix small. Do not refactor unrelated code in the same change.
7. Regression test
- Write a test that fails on the old code for the right reason, then passes with the fix. Run it both ways: stash or revert the fix temporarily and confirm it fails.
- Run the surrounding test suite to check you broke nothing.
- Re-run the original reproduction from step 1.
When fixes keep failing
Stop editing: a fix that does not work means your model of the system is wrong. Then:
- List what each attempt disproved.
- Re-check the assumptions you never tested: is this the code that runs? the right config? a stale build?
- Report to the user what is ruled out and what you need from them.
Report format
- Symptom: one line, with the exact error.
- Root cause: what and where (file and function), with the evidence.
- Fix: what changed and why it addresses the cause.
- Test: the regression test name and proof that it failed before.
- Not verified: anything you could not check (other environments, production data).
Pitfalls
- "It works now" after a change you cannot explain is not a fix. Flaky bugs also "work" after random changes.
- Do not widen timeouts, add retries or swallow exceptions to hide the failure unless the cause is genuinely external, and then say so.
- Do not trust comments, variable names or old docs over what the code does when you run it.
- Do not leave debug prints, temporary files or commented-out experiments in the final diff.
- Do not delete data, reset the database or discard uncommitted work to get a clean state without asking the user.
- A bug in a dependency is possible but rare. Prove it with a minimal reproduction before blaming the library.
Source: AnyModel skills catalog · License: CC BY 4.0
Connect through AnyModel API
This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.
AnyModel