Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or investigate why something is not working; especially for complex or intermittent issues across multiple components. Applies the Five Whys method, hypothesis-driven testing, stack trace analysis, git blame/log evidence gathering, and causal chain documentation to isolate and confirm root causes before applying any fix.
81
77%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./packages/core/src/methodology/packs/debugging/root-cause-analysis/SKILL.mdQuality
Discovery
92%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly articulates what the skill does (systematic root cause analysis using specific methodologies) and when to use it (bugs, crashes, errors, broken behavior). The trigger terms are natural and comprehensive. The main weakness is potential overlap with general debugging skills, though the emphasis on structured investigation and root cause methodology provides some differentiation.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Five Whys method, hypothesis-driven testing, stack trace analysis, git blame/log evidence gathering, causal chain documentation.' Also specifies the goal: 'isolate and confirm root causes before applying any fix.' | 3 / 3 |
Completeness | Clearly answers both 'what' (systematic root cause analysis through structured investigation phases, Five Whys, hypothesis-driven testing, etc.) and 'when' (explicit 'Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or investigate'). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'bug', 'crash', 'error', 'broken behavior', 'debug', 'troubleshoot', 'investigate', 'not working', 'intermittent issues'. These are highly natural phrases a user would use when encountering problems. | 3 / 3 |
Distinctiveness Conflict Risk | While the focus on root cause analysis methodology is distinctive, terms like 'bug', 'error', 'debug', and 'troubleshoot' are very common and could overlap with general debugging or code-fixing skills. The emphasis on structured investigation and 'not just treating symptoms' helps differentiate, but there's still meaningful overlap risk with simpler fix-it skills. | 2 / 3 |
Total | 11 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid methodological skill with a well-structured investigation workflow and good validation checkpoints. Its main weaknesses are moderate verbosity (explaining concepts Claude likely already understands, like common root cause categories) and guidance that is more framework-oriented than concretely actionable. The workflow sequencing and verification gates are the strongest aspects.
Suggestions
Trim the 'Common Root Cause Categories' section — Claude already knows these; at most keep it as a brief checklist rather than an explanatory list.
Make Phase 2 and Phase 3 more actionable by providing concrete command sequences or code snippets for each evidence-gathering step, similar to the 'Evidence Collection Commands' section.
Consider extracting the documentation template and hypothesis table format into a separate reference file to improve progressive disclosure and reduce the main skill's length.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably well-structured but includes some unnecessary elaboration. The 'Common Root Cause Categories' section lists things Claude already knows, and some phases could be tightened (e.g., Phase 2's 'Do NOT' list is somewhat obvious). The Five Whys explanation is concise, but overall there's moderate padding. | 2 / 3 |
Actionability | The skill provides a structured methodology with concrete bash commands for evidence gathering and a documentation template, but much of the content is procedural guidance rather than executable steps. The hypothesis table is a good example format, but the phases are more descriptive frameworks than copy-paste-ready instructions. It reads more like a methodology guide than a concrete action plan. | 2 / 3 |
Workflow Clarity | The five investigation phases are clearly sequenced with explicit validation checkpoints (Phase 5 has a verification checklist, Phase 4 has clear decision logic for rejected hypotheses). The workflow includes feedback loops — rejected hypotheses lead to re-evaluation, and the Phase 5 checklist gates the transition from investigation to fix. Red flags section serves as an additional validation checkpoint. | 3 / 3 |
Progressive Disclosure | The content is well-organized with clear sections and headers, but it's a monolithic document with no bundle files to offload detail into. The 'Integration with Other Skills' section references other skills but the main content could benefit from splitting detailed phases or the documentation template into separate referenced files. For a skill of this length (~120 lines of content), some content is inline that could be separated. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
a9e5c83
Table of Contents
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.