Root-Cause Debugger

---
name: root-cause-debugger
description: "Finds the real cause of a software bug before anyone patches it: pins down a reliable reproduction, separates where the error shows from where it starts, ranks hypotheses with the cheapest test that would rule each one out, keeps an elimination log, states the cause in one sentence (because X, Y happens when Z), then gives a minimal fix and a regression test that fails before the fix. Use when the user says 'help me debug this', 'why does this fail', 'intermittent bug', 'it works on my machine', 'the fix didn't stick' or 'find the root cause'."
license: "Proprietary. © 2026 Meevra (meevra.com). Licensed for personal and internal business use; no resale or redistribution."
compatibility: "Claude Code, Codex, Cursor and Antigravity (SKILL.md folder; can run the tests itself); Claude apps (upload under Customize > Skills); ChatGPT through a plugin; or paste this file into any chat with the error and code."
metadata:
  title: "Root-Cause Debugger"
  summary: "A disciplined search for the real cause of a bug, with the cheapest test for each suspect and no fix until the cause fits in one sentence."
  pack: "code-agents"
  models: "claude, chatgpt, gemini, deepseek, claude-code, codex, cursor, antigravity"
  free: "true"
  version: "3"
  updated: "2026-10-15"
  verified_on: ""
---

# Root-Cause Debugger

The search that finds the bug, not the patch that hides it. Ask a model "why does this fail?" and it will usually offer a plausible fix at once. Sometimes that is right. When it is not, the bug comes back a week later. This skill holds back the fix until the cause can be written as one sentence that explains every symptom, and it chooses tests by how cheaply they rule a suspect out.

**How this skill runs:** in a coding agent it can run the reproduction and the tests itself, and it shows real output. In a chat it asks you to run each test and report back; it never claims a result it did not see. Install the folder as a skill, or paste this file into any chat followed by your bug report.

## When to use
- A bug keeps coming back after "fixes".
- An intermittent failure, a "works on my machine" issue, or a stack trace pointing at code that looks fine.
- You want to understand a bug, not just silence it.

## When not to use
- An obvious typo or syntax error with a clear message. Just fix it.
- A live production incident. Restore service first (roll back, switch off the feature), then use this for the investigation.

## Inputs to ask for
Ask once, only for what is missing:
- The symptom: the exact error and stack trace, or the wrong output next to the expected output.
- Environment: language and version, framework, OS, where it runs (local, container, cloud), relevant config.
- How often it happens and under what conditions, and when it started (after which change or deploy, if known).
- The relevant code, what was already tried, and what happened.
- Logs from around the failure.

## Workflow
1. **Reproduce.** Write the exact steps and environment that trigger the bug every time. If it is intermittent, list what differs between failing and passing runs: data, timing, load, order, environment, version. That difference is the main clue.
2. **Find where it starts.** Where the error shows is often not where it starts. Trace backwards: which state or input sends this path wrong, and where could that state have been set?
3. **Line up hypotheses,** ranked by likelihood for this case. A useful default order is shared or stale state, boundaries and off-by-one, async timing and races, caching, environment and config, then rare causes (compiler, library bug, hardware). For each, give the cheapest test that would rule it out: one log line, an assertion, one specific input, comparing config between environments, or `git bisect` between a good and a bad commit.
4. **Eliminate.** Run or request one test at a time. After each, record the result, what it rules out and what remains. Change one thing at a time.
5. **State the root cause** in the form "Because [mechanism], [symptom] happens when [condition]." The sentence has to explain every observed symptom, including the ones that seemed unrelated. If it cannot be written that way yet, go back to step 3.
6. **Fix and protect.** Give the smallest fix and why it does not affect nearby behaviour. Add a regression test that fails before the fix and passes after, ideally one that catches this class of bug and not just this instance. If you can run tests, show both runs.

Keep observation and inference apart throughout: what the logs and outputs show, and what you conclude from them. If confirming a hypothesis needs code you have not seen, ask for it instead of assuming what it contains.

## Output format
```
## Reproduction
Steps: ... · Differs between pass and fail: ...
## Where it shows vs where it may start
...
## Hypotheses
| # | hypothesis | likelihood | cheapest test | status |
## Elimination log
- test → result (seen) → rules out ... → remaining ...
## Root cause
Because ..., ... happens when ...
## Fix and regression test
<minimal diff> · Why it is safe: ... · Test: <fails before, passes after>
```

## Example
**User:** Our Node.js API sometimes returns another user's cart. Roughly 1 in 500 requests, only in production. Express with a Redis cache.

**Result (excerpt):**
```
## Reproduction
Differs between pass and fail: only under concurrent load; never locally with one user. Try 50 parallel users against staging.
## Hypotheses
| 1 | a module-level variable holds the current user across an await | high | search the cart service for top-level let/var | open |
| 2 | a cache key misses the user id on one path | medium | log every cache key for an hour | open |
| 3 | a CDN caches signed-in responses | low | check Cache-Control on /cart | open |
## Elimination log
- search → `let currentUserId` at module scope in cartService.js, set before `await redis.get()` (seen) → supports 1 → test 2 and 3 next to be sure
- Cache-Control on /cart is "private, no-store" (seen) → rules out 3
## Root cause
Because currentUserId is shared module state, a second request overwrites it during the Redis await, so the first request reads the wrong cart when two requests overlap.
## Fix and regression test
Pass userId as an argument through getCart(). Test: two concurrent requests for different users each get their own cart; fails on the current code, passes with the fix.
```
_Illustrative example written by Meevra; your model's wording will differ._

## Model notes (Oct 2026)
- **Claude:** Claude Opus 5.5 at the default effort handles most bugs; raise effort for concurrency and state bugs (in Claude Code, `/effort high`, or include "ultrathink" for one turn). Install in Claude Code as `.claude/skills/root-cause-debugger/SKILL.md`, or upload the folder as a ZIP under Customize > Skills in the Claude apps (code execution needs to be on).
- **ChatGPT:** use High on the Thinking slider for intermittent bugs. GPT-6 tends to ask questions; the "Inputs to ask for" list keeps that to one round.
- **Codex:** GPT-6.1 Sol can run the reproduction and `git bisect` itself. Install in `.agents/skills/` and call it with `$root-cause-debugger`.
- **Cursor:** install in `.cursor/skills` or `.agents/skills` and call it with `/`.
- **Gemini and Antigravity:** put logs and code first and the question last. Antigravity loads workspace skills from `.agents/skills/`; choose a higher effort with `/effort` in the CLI for hard bugs.
- **DeepSeek:** DeepSeek-V4.1-Flash thinks by default at high effort; use max for the hardest cases. It reads screenshots of errors natively, but pasted text is easier to search.

## Troubleshooting
- **It proposes a fix straight away.** Reply: "No fix yet. Give the hypothesis table and the cheapest test for the top one."
- **It reports a test result you never gave it.** Ask it to mark every result as seen or expected, and to wait for your output.
- **The root-cause sentence does not explain every symptom.** Point to the symptom it leaves out and ask it to return to the hypotheses.
- **The "fix" works but nobody knows why.** Then the bug is still there. Ask for the root-cause sentence before you merge.

---
© 2026 Meevra · meevra.com · Licensed to the purchaser for personal and internal business use.