Menu
Systematically diagnoses bugs by tracing execution flow and identifying root causes vs symptoms.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Runs a systematic checklist review on any code diff or file, covering correctness, security, performance, and readability.
Writes a high-quality CLAUDE.md, .cursorrules, or .windsurfrules file that gives a coding agent the right project context, conventions, and constraints to work effectively.
Designs an eval suite for an LLM agent or pipeline including success metrics, trajectory scoring, LLM-as-judge setup, and regression test cases.
Designs a hybrid retrieval pipeline combining dense vector search and BM25 sparse search with reciprocal rank fusion, and explains when to use each configuration.
Converts a workflow description into a LangGraph node/edge graph with typed state, conditional routing, and human-in-the-loop checkpoints.
Audits an AI application for unnecessary token spend and recommends prompt caching, model routing, and token reduction techniques to cut costs.
| name | Bug Root Cause Analyzer |
| description | Systematically diagnoses bugs by tracing execution flow and identifying root causes vs symptoms. |
| category | coding |
| tags | ["debugging","root-cause","analysis"] |
| author | simplyutils |
This skill directs the agent to work through a bug methodically โ distinguishing the root cause from the symptoms, tracing the execution path that led to the failure, and producing a clear diagnosis before suggesting a fix. It applies the 5-Why technique, reads stack traces carefully, and avoids the trap of patching the symptom without understanding the cause.
Use this when you have a bug that isn't immediately obvious, when a quick fix didn't hold, or when you want to understand why something broke before deciding how to fix it.
Copy this file to .agents/skills/bug-root-cause-analyzer/SKILL.md in your project root.
Then ask:
Provide as much context as you can: the error message, the stack trace, the relevant code, and what you expected to happen.
Add the instructions below to your .cursorrules or paste them into the Cursor AI pane before describing the bug.
When asked to diagnose a bug, follow this process:
Before analyzing, make sure you have:
If any of these are missing, ask for them before proceeding.
For each "why", look for evidence in the code rather than guessing:
Stop when you reach a level where a code change would prevent the bug from occurring in the first place.
Assign one of these root cause categories:
## Bug Diagnosis
### Symptom
[What the user observed โ the error message and where it appeared]
### Root Cause
[One or two sentences describing the actual cause, not the symptom]
### Root Cause Category
[One of the categories from Phase 4]
### Execution Path
1. [Entry point]
2. [Next call in the chain]
3. โ [Where the failure condition was set]
4. โ [Where the error was thrown]
### 5-Why Chain
- Why did X fail? โ Because Y was null
- Why was Y null? โ Because Z function returned early without populating it
- Why did Z return early? โ Because the input failed a guard clause
- Why did the input fail? โ Because the API response schema changed and field `foo` is now nested differently
### Recommended Fix
[A specific, targeted fix that addresses the root cause, not the symptom]
### What NOT to do
[If there's an obvious but wrong fix that patches the symptom, call it out]
Input to Agent:
"Getting this error in production. Use the Bug Root Cause Analyzer skill.
TypeError: Cannot read properties of undefined (reading 'price') at calculateTotal (checkout.ts:47) at handleSubmit (CheckoutPage.tsx:112) at HTMLButtonElement.onClick
checkout.ts:47is:const total = items.reduce((sum, item) => sum + item.product.price * item.quantity, 0);"
Output from Agent:
Bug Diagnosis
Symptom
TypeError: Cannot read properties of undefined (reading 'price') thrown at checkout.ts:47 when handleSubmit is called.
Root Cause
At least one item in the items array has an undefined product field. The reduce assumes every item has a populated product object, but this assumption is violated when an item is in the cart but its product has been deleted or failed to load.
Root Cause Category Missing validation / null dereference
Execution Path
CheckoutPage.tsx:112 โ handleSubmithandleSubmit calls calculateTotal(items)checkout.ts:47 iterates items โ one item has product: undefined.price on undefined throws TypeError5-Why Chain
.price throw? โ item.product is undefinedproduct undefined? โ The product was deleted from the DB after being added to the cartcalculateTotal assumed the cart was always valid when calledRecommended Fix
Filter out orphaned cart items before calling calculateTotal, and display a warning to the user that an item was removed:
const validItems = items.filter(item => item.product != null);
const total = calculateTotal(validItems);
Also add a guard in calculateTotal itself as a defensive measure.
What NOT to do
Do not just add item.product?.price ?? 0 in the reduce. That silently includes a $0 item in the total, which is confusing and could result in incorrect orders.