amnafarzy/ravie/debug-root-cause
Claude Code and agent skill by amnafarzy/ravie
- community
Checking that the SKILL.md file is still in the repository.
Use this whenever something fails before it has shipped — failing tests, broken builds, wrong UI behavior, preview errors — and the cause is unknown, even if the user just pastes an error. Diagnose before fixing. Production failures (main branch, live users) → observability-incident- loop.
Install
npx vskill@latest install amnafarzy/ravie/debug-root-causeSKILL.md
The same SKILL.md was published earlier as amnafarzy/ravie/debug-root-cause.
debug-root-cause
Find the actual cause of a bug instead of patching symptoms. The skill that prevents the failure mode where AI keeps adding try/catch until the error message goes away.
Purpose
Debug methodically: reproduce, gather evidence, isolate, hypothesize, test, fix at the smallest scope, verify, document.
Stack integration
Reads from:
- GitHub: code, recent diffs, blame
- Linear: the bug issue, related context
- Vercel: build logs, runtime logs, deployment history
- Supabase: query logs, auth logs, RLS policy state, recent migrations
- Browser: console errors, network tab, source maps
- VPS/automation server: job logs, retry history
- Notion: any related runbook or prior incident notes
Writes to:
- The fix itself (in code)
- Regression test or check (if practical)
- PR notes describing root cause + fix
- Linear comments
- Notion runbook entry (only if the bug is durable / will recur)
Inputs required
- Expected behavior: what should happen
- Actual behavior: what is happening
- Reproduction steps: minimal sequence to trigger
- Error messages and logs: actual text, not paraphrased
- Recent changes: what merged/deployed recently
- Environment: local / preview / production
- Linear issue or PR if one exists
Process
0. Read context hygiene first
Before debugging, read rules/context-hygiene.md so the session stays evidence-based and does not drift into speculative patches.
1. Restate the problem precisely
"It's broken" is not a problem statement. Force precision:
- Expected: [exact expected behavior]
- Actual: [exact observed behavior]
- Frequency: [always / sometimes / once]
- When started: [if known]
If the user can't describe it precisely yet, the first job is to extract that — not to fix.
2. Reproduce it
You can't fix what you can't reproduce.
- Get the exact steps
- Run them in the same environment if possible (or document why you can't)
- If it's environment-specific (only prod), document conditions clearly
If you can't reproduce: stop guessing. Either gather more data or escalate to "needs more info" status.
3. Capture exact evidence
Don't paraphrase errors. Copy them verbatim:
- Full error message
- Stack trace
- Console output
- Network request/response
- Database query and response
- Relevant log lines with timestamps
4. Check what changed recently
Most bugs come from recent changes:
Also check:
- Recent Vercel deployments
- Recent Supabase migrations
- Recent package updates
- Recent CLAUDE.md changes (rare but possible)
5. Find the smallest failing path
Bisect:
- If it broke between commits, find the bad commit
- If it's a UI bug, find the component that's actually wrong (not just the visible symptom)
- If it's a data bug, trace from input → mutation → output and find where it diverges
6. Form a hypothesis
A hypothesis is "X causes Y because Z." Not "maybe it's the auth thing."
If you can't form a specific hypothesis, you don't have enough evidence yet. Go back to step 3.
7. Test the hypothesis
The cheapest test that would prove it right or wrong. Examples:
- Add a
console.logand check what value flows through - Run a SQL query directly against Supabase
- Comment out a line and see if behavior changes
- Revert the suspect commit and see if the bug disappears
8. Apply the smallest possible fix
Once you know the cause:
- Fix at the source, not downstream
- Don't refactor adjacent code
- Don't "improve" things while you're there
- Don't fix multiple bugs in one change
9. Verify the fix
- Run the original reproduction steps
- Run the full check suite (typecheck, lint, test, build)
- Test edge cases related to the bug
- If the bug was data-related, verify with actual data not mock
10. Add regression coverage
If practical:
- Write a test that fails before your fix and passes after
- Add a runtime assertion if a test isn't possible
- Document the failure mode in a code comment
If the bug was environmental (only happens in prod), document the trigger conditions in the runbook.
11. Document the root cause
In the PR or Linear comment:
- What the symptom was
- What the actual cause was
- Why the original code was wrong
- What the fix does
- What edge cases were considered
This is for future-you. The minute the fix lands, you'll forget why.
Output format
Approval gates
Tier 1-2 — investigating, drafting fix, running checks: no approval needed.
Tier 3 — pushing fix branch, opening PR, updating Linear: standard PR approval.
Tier 4 — needs explicit approval each time:
- Production hotfix (not the normal PR cycle)
- Rollback to previous version
- Production data repair (UPDATE/DELETE on real data)
- Disabling tests (almost never the right call)
- Changing secrets or permissions
Tier 5 — always blocked:
- Mutating production data without explicit approval naming exact rows/effects
- Suppressing errors with try/catch to make symptoms disappear
- Deleting tests to bypass them
Hard rules
- Never patch randomly — every change should follow from a hypothesis
- Never suppress errors without understanding them
- Never delete tests to make checks pass
- Never mutate production data without explicit approval
- Never claim a fix works without verifying with the original reproduction
- Never close a Linear bug without the root cause documented
- Never trust "it's working now" without reproducing the original failure first
Connects to
current-docs-guard— invoke if the bug might be from outdated API usagesupabase-guardian— invoke if the bug involves DB / RLS / authvercel-preview-qa— invoke if the bug is preview-environment-specificautomation-sre— invoke if the bug is in an VPS/automation server jobobservability-incident-loop— invoke if this is a production incidentissue-to-pr— the fix flows through normal PR cycle unless it's a hotfixdecision-log-adr— if the fix changes architecture, log itskill-creator— if the bug class is recurring, codify it into a skill update
Common failure modes
Patching symptoms — The most common AI failure. Adding ?. everywhere, wrapping things in try/catch, defaulting to empty objects. These hide the bug. Always ask: why is this value undefined? Then fix the cause.
Skipping reproduction — Reading the error message and immediately writing a fix. Don't. Reproduce first, even if you "know" what's wrong.
Fixing too much — While in the suspect file, also "improving" adjacent code. Don't. Fix the bug. Open follow-up issues for everything else.
Stopping at first plausible cause — There might be two bugs interacting. If your fix doesn't reproduce-pass-cleanly, keep investigating.
Not capturing the root cause in writing — In 3 weeks you'll see this bug pattern again and have no record of why it happened. Always write the post-mortem in PR/Linear.
Treating "it's intermittent" as unfixable — Intermittent bugs almost always have a real cause (race condition, state leak, timing). They're not random. They're a clue you haven't found the actual trigger yet.
Security
- Security scanPassed, 98 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/debug-root-cause/SKILL.md
Popularity
- Repository stars
- 3
- 7-day trend score
- 7
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/amnafarzy/ravie/debug-root-cause)