{"id":"bc0e7c40-5fd9-463b-a1a9-a2fe085629b6","shortId":"k6afZq","kind":"skill","title":"Bug Root Cause Analyzer","tagline":"Systematically diagnoses bugs by tracing execution flow and identifying root causes vs symptoms.","description":"# Bug Root Cause Analyzer\n\n## What this skill does\n\nThis 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.\n\nUse 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.\n\n## How to use\n\n### Claude Code / Cline\n\nCopy this file to `.agents/skills/bug-root-cause-analyzer/SKILL.md` in your project root.\n\nThen ask:\n- *\"I'm getting a TypeError in checkout. Use the Bug Root Cause Analyzer skill to diagnose it.\"*\n- *\"This test is flaky and I don't know why. Use the Bug Root Cause Analyzer skill.\"*\n\nProvide as much context as you can: the error message, the stack trace, the relevant code, and what you expected to happen.\n\n### Cursor\n\nAdd the instructions below to your `.cursorrules` or paste them into the Cursor AI pane before describing the bug.\n\n## The Prompt / Instructions for the Agent\n\nWhen asked to diagnose a bug, follow this process:\n\n### Phase 1 — Gather information\n\nBefore analyzing, make sure you have:\n- The exact error message (not paraphrased)\n- The full stack trace if available\n- The code where the error originates\n- What the user expected to happen vs what actually happened\n- When the bug started (after a deploy? a specific change?)\n\nIf any of these are missing, ask for them before proceeding.\n\n### Phase 2 — Read the stack trace\n\n1. Start at the **top of the stack trace** — this is where the error was thrown, not necessarily where the bug lives.\n2. Work **downward** through the frames until you reach application code (skip framework internals unless you have good reason to look there).\n3. Identify the **last application-code frame** before the error — this is usually where the bug lives.\n4. Note the **call chain** from entry point to failure point.\n\n### Phase 3 — Apply 5-Why analysis\n\nFor each \"why\", look for evidence in the code rather than guessing:\n\n1. **Why did the error occur?** (What specific condition triggered it?)\n2. **Why was that condition true?** (What state led to it?)\n3. **Why was the program in that state?** (What upstream code set that state?)\n4. **Why did upstream code behave that way?** (Is this a logic error, a data issue, a race condition?)\n5. **Why does that root condition exist?** (Is this a design flaw, a missing validation, an incorrect assumption?)\n\nStop when you reach a level where a code change would prevent the bug from occurring in the first place.\n\n### Phase 4 — Classify the bug\n\nAssign one of these root cause categories:\n- **Logic error** — incorrect conditional, wrong operator, off-by-one\n- **Null/undefined dereference** — missing null check, optional chaining needed\n- **Type mismatch** — wrong type assumption, implicit coercion\n- **Race condition** — async operations in wrong order, missing await, shared state mutation\n- **Missing validation** — user input or API response not validated before use\n- **Stale data / cache** — reading data that has changed or expired\n- **Dependency bug** — the bug is in a library, not your code\n- **Environment difference** — works locally, fails in production due to config or OS difference\n\n### Phase 5 — Output your diagnosis\n\n```markdown\n## Bug Diagnosis\n\n### Symptom\n[What the user observed — the error message and where it appeared]\n\n### Root Cause\n[One or two sentences describing the actual cause, not the symptom]\n\n### Root Cause Category\n[One of the categories from Phase 4]\n\n### Execution Path\n1. [Entry point]\n2. [Next call in the chain]\n3. → [Where the failure condition was set]\n4. → [Where the error was thrown]\n\n### 5-Why Chain\n- Why did X fail? → Because Y was null\n- Why was Y null? → Because Z function returned early without populating it\n- Why did Z return early? → Because the input failed a guard clause\n- Why did the input fail? → Because the API response schema changed and field `foo` is now nested differently\n\n### Recommended Fix\n[A specific, targeted fix that addresses the root cause, not the symptom]\n\n### What NOT to do\n[If there's an obvious but wrong fix that patches the symptom, call it out]\n```\n\n## Example\n\n**Input to Agent:**\n> \"Getting this error in production. Use the Bug Root Cause Analyzer skill.\n>\n> ```\n> TypeError: Cannot read properties of undefined (reading 'price')\n>     at calculateTotal (checkout.ts:47)\n>     at handleSubmit (CheckoutPage.tsx:112)\n>     at HTMLButtonElement.onClick\n> ```\n>\n> `checkout.ts:47` is: `const total = items.reduce((sum, item) => sum + item.product.price * item.quantity, 0);`\"\n\n**Output from Agent:**\n\n**Bug Diagnosis**\n\n**Symptom**\n`TypeError: Cannot read properties of undefined (reading 'price')` thrown at `checkout.ts:47` when `handleSubmit` is called.\n\n**Root Cause**\nAt 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.\n\n**Root Cause Category**\nMissing validation / null dereference\n\n**Execution Path**\n1. User clicks Submit → `CheckoutPage.tsx:112` → `handleSubmit`\n2. `handleSubmit` calls `calculateTotal(items)`\n3. `checkout.ts:47` iterates `items` — one item has `product: undefined`\n4. Accessing `.price` on `undefined` throws TypeError\n\n**5-Why Chain**\n- Why did `.price` throw? → `item.product` is `undefined`\n- Why is `product` undefined? → The product was deleted from the DB after being added to the cart\n- Why is there no guard? → `calculateTotal` assumed the cart was always valid when called\n- Why was this assumption wrong? → Cart items are stored by product ID but products can be deleted independently\n\n**Recommended Fix**\nFilter out orphaned cart items before calling `calculateTotal`, and display a warning to the user that an item was removed:\n```typescript\nconst validItems = items.filter(item => item.product != null);\nconst total = calculateTotal(validItems);\n```\nAlso add a guard in `calculateTotal` itself as a defensive measure.\n\n**What NOT to do**\nDo 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.\n\n## Notes\n\n- The more context you provide (full stack trace, surrounding code, recent changes), the more accurate the diagnosis will be.\n- For flaky tests, describe the failure pattern (always fails, fails 1 in 10 runs, fails only in CI) — this is a key clue for diagnosing race conditions.\n- This skill produces a diagnosis and a recommendation. It does not apply the fix automatically — review the recommendation before implementing it.","tags":["bug","root","cause","analyzer","openagentskills","notysoty","agent-skills","claude","claude-code","claude-skills","cline","cursor"],"capabilities":["skill","source-notysoty","skill-bug-root-cause-analyzer","topic-agent-skills","topic-claude","topic-claude-code","topic-claude-skills","topic-cline","topic-cursor","topic-llm","topic-llm-skills","topic-skills"],"categories":["openagentskills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Notysoty/openagentskills/bug-root-cause-analyzer","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Notysoty/openagentskills","source_repo":"https://github.com/Notysoty/openagentskills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (6,899 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:20.833Z","embedding":null,"createdAt":"2026-05-18T13:20:41.299Z","updatedAt":"2026-05-18T19:13:20.833Z","lastSeenAt":"2026-05-18T19:13:20.833Z","tsv":"'0':764,982,990 '1':227,291,382,614,842,1034 '10':1036 '2':286,313,393,617,848 '3':335,365,404,623,853 '4':353,418,476,611,630,862 '5':65,367,437,570,636,869 'access':863 'accur':1019 'actual':262,597 'ad':892 'add':192,962,979 'address':696 'agent':30,216,725,767 'agents/skills/bug-root-cause-analyzer/skill.md':128 'ai':205 'also':961 'alway':906,1031 'analysi':369 'analyz':4,21,147,167,231,736 'api':529,678 'appear':588 'appli':63,366,1062 'applic':322,340 'application-cod':339 'array':795 'ask':134,218,280 'assign':480 'assum':803,902 'assumpt':454,509,813,913 'async':514 'automat':1065 'avail':247 'avoid':73 'await':520 'behav':423 'broke':111 'bug':1,7,18,35,90,144,164,210,222,266,311,351,468,479,546,548,575,733,768 'cach':537 'calculatetot':747,851,901,937,959,966 'call':356,619,719,785,850,909,936 'cannot':739,772 'care':71 'cart':822,895,904,915,933 'categori':486,604,608,835 'caus':3,15,20,40,83,146,166,485,590,598,603,699,735,787,834 'chain':357,503,622,638,871 'chang':273,464,542,681,1016 'check':501 'checkout':141 'checkout.ts:47':748,754,781,854 'checkoutpage.tsx:112':751,846 'ci':1041 'classifi':477 'claud':121 'claus':670 'clear':56 'click':844 'cline':123 'clue':1046 'code':122,184,249,323,341,378,414,422,463,555,1014 'coercion':511 'condit':390,397,436,442,490,513,627,1050 'config':565 'confus':997 'const':756,951,957 'context':172,1007 'copi':124 'could':999 'cursor':191,204 'cursorrul':198 'data':432,536,539 'db':889 'decid':113 'defens':970 'delet':828,886,926 'depend':545 'deploy':270 'derefer':498,839 'describ':208,595,1027 'design':447 'diagnos':6,150,220,1048 'diagnosi':57,573,576,769,1021,1055 'didn':100 'differ':557,568,688 'direct':28 'display':939 'distinguish':37 'downward':315 'due':563 'earli':655,663 'entri':359,615 'environ':556 'error':177,238,252,304,345,386,430,488,583,633,728 'everi':804 'evid':375 'exact':237 'exampl':722 'execut':10,46,612,840 'exist':443 'expect':188,257 'expir':544 'fail':560,642,667,675,830,1032,1033,1038 'failur':52,362,626,1029 'field':683,800 'file':126 'filter':930 'first':473 'fix':61,99,116,690,694,714,929,1064 'flaki':155,1025 'flaw':448 'flow':11 'follow':223 'foo':684 'frame':318,342 'framework':325 'full':243,1010 'function':653 'gather':228 'get':137,726 'good':330 'guard':669,900,964 'guess':381 'handlesubmit':750,783,847,849 'happen':190,259,263 'hold':102 'htmlbuttonelement.onclick':753 'id':921 'identifi':13,336 'immedi':94 'implement':1070 'implicit':510 'includ':988 'incorrect':453,489,1002 'independ':927 'inform':229 'input':527,666,674,723 'instruct':194,213 'intern':326 'isn':92 'issu':433 'item':760,791,794,805,818,852,856,858,916,934,947,954,991 'item.product':876,955,980 'item.product.price':762 'item.quantity':763 'items.filter':953 'items.reduce':758 'iter':855 'key':1045 'know':160 'last':338 'least':789 'led':49,401 'level':460 'librari':552 'live':312,352 'load':832 'local':559 'logic':429,487 'look':333,373 'm':136 'make':232 'markdown':574 'measur':971 'messag':178,239,584 'method':36 'mismatch':506 'miss':279,450,499,519,524,836 'much':171 'mutat':523 'necessarili':308 'need':504 'nest':687 'next':618 'note':354,1004 'null':500,646,650,838,956 'null/undefined':497 'object':810 'observ':581 'obvious':95,711 'occur':387,470 'off-by-on':493 'one':481,496,591,605,790,857 'oper':492,515 'option':502 'order':518,1003 'origin':253 'orphan':932 'os':567 'output':571,765 'pane':206 'paraphras':241 'past':200 'patch':77,716 'path':47,613,841 'pattern':1030 'phase':226,285,364,475,569,610 'place':474 'point':360,363,616 'popul':657,808 'prevent':466 'price':745,778,864,874,981 'proceed':284 'process':225 'produc':54,1053 'product':562,730,799,809,825,860,881,884,920,923 'program':408 'project':131 'prompt':212 'properti':741,774 'provid':169,1009 'quick':98 'race':435,512,1049 'rather':379 'reach':321,458 'read':68,287,538,740,744,773,777 'reason':331 'recent':1015 'recommend':689,928,1058,1068 'reduc':802,985 'relev':183 'remov':949 'respons':530,679 'result':1000 'return':654,662 'review':1066 'root':2,14,19,39,132,145,165,441,484,589,602,698,734,786,833 'run':1037 'schema':680 'sentenc':594 'set':415,629 'share':521 'silent':987 'skill':24,27,148,168,737,1052 'skill-bug-root-cause-analyzer' 'skip':324 'someth':110 'source-notysoty' 'specif':272,389,692 'stack':69,180,244,289,298,1011 'stale':535 'start':267,292 'state':400,411,417,522 'stop':455 'store':918 'submit':845 'suggest':59 'sum':759,761 'sure':233 'surround':1013 'symptom':17,43,79,577,601,702,718,770 'systemat':5 'target':693 'techniqu':67 'test':153,1026 'throw':867,875 'thrown':306,635,779 'top':295 'topic-agent-skills' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-cline' 'topic-cursor' 'topic-llm' 'topic-llm-skills' 'topic-skills' 'total':757,958,994 'trace':9,44,70,181,245,290,299,1012 'trap':75 'trigger':391 'true':398 'two':593 'type':505,508 'typeerror':139,738,771,868 'typescript':950 'undefin':743,776,798,861,866,878,882 'understand':81,108 'unless':327 'upstream':413,421 'use':84,120,142,162,534,731 'user':256,526,580,843,944 'usual':348 'valid':451,525,532,837,907 'validitem':952,960 'violat':815 'vs':16,260 'want':106 'warn':941 'way':425 'without':80,656 'work':32,314,558 'would':465 'wrong':491,507,517,713,914 'x':641 'y':644,649 'z':652,661","prices":[{"id":"e2818ac7-2c80-4c31-97b0-a2ed46ff172d","listingId":"bc0e7c40-5fd9-463b-a1a9-a2fe085629b6","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Notysoty","category":"openagentskills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:41.299Z"}],"sources":[{"listingId":"bc0e7c40-5fd9-463b-a1a9-a2fe085629b6","source":"github","sourceId":"Notysoty/openagentskills/bug-root-cause-analyzer","sourceUrl":"https://github.com/Notysoty/openagentskills/tree/main/skills/bug-root-cause-analyzer","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:41.299Z","lastSeenAt":"2026-05-18T19:13:20.833Z"}],"details":{"listingId":"bc0e7c40-5fd9-463b-a1a9-a2fe085629b6","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Notysoty","slug":"bug-root-cause-analyzer","github":{"repo":"Notysoty/openagentskills","stars":8,"topics":["agent-skills","claude","claude-code","claude-skills","cline","cursor","llm","llm-skills","skills"],"license":"mit","html_url":"https://github.com/Notysoty/openagentskills","pushed_at":"2026-03-28T06:50:19Z","description":"A  community-driven library of reusable AI agent skills for Claude Code, Cursor, Codex, Cline, and more.","skill_md_sha":"d648728e0cbf02a88820c1e6d2ca8ab00462e106","skill_md_path":"skills/bug-root-cause-analyzer/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Notysoty/openagentskills/tree/main/skills/bug-root-cause-analyzer"},"layout":"multi","source":"github","category":"openagentskills","frontmatter":{"name":"Bug Root Cause Analyzer","description":"Systematically diagnoses bugs by tracing execution flow and identifying root causes vs symptoms."},"skills_sh_url":"https://skills.sh/Notysoty/openagentskills/bug-root-cause-analyzer"},"updatedAt":"2026-05-18T19:13:20.833Z"}}