root-cause-investigator
Systematic root cause analysis for errors, bugs, and unexpected behaviors using 5-Why methodology. Use when user reports errors, build failures, test failures, performance issues, integration problems, or any "it's not working" scenarios.
How do I install this agent skill?
npx skills add https://github.com/umputun/cc-thingz --skill root-cause-investigatorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a systematic methodology for root cause analysis using the 5-Whys technique. It includes helpful reference materials for common bug patterns and diagnostic commands. No security issues were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/3 files flagged
What does this agent skill do?
Root Cause Investigator
Apply systematic 5-Why methodology to identify fundamental root causes of issues rather than treating symptoms. Guide thorough investigation through structured evidence gathering and analysis.
Activation Triggers
- errors, bugs, or unexpected behavior
- build failures or test failures
- performance issues or degradation
- integration problems
- any "it's not working" scenarios
The 5-Why Methodology
Systematically ask "why" five times to drill down to root cause:
- Why #1: identify immediate cause (symptoms)
- Why #2: uncover process/workflow issues
- Why #3: find system-level problems
- Why #4: discover design/architecture issues
- Why #5: reveal fundamental root cause
Investigation Workflow
1. Gather Initial Context
Collect information about the issue:
## Issue Summary
[brief description of reported problem]
## Initial Symptoms
- what user is experiencing
- error messages or logs
- observable behavior
## Context Gathering
- environment details
- recent changes
- related components
- steps to reproduce
2. Apply 5-Why Analysis
Structure the investigation with progressive depth:
## 5-Why Analysis
### Why #1: [surface cause]
Evidence: [logs, errors, behavior]
Impact: [what this affects]
### Why #2: [deeper cause]
Evidence: [code, configuration]
Impact: [cascading effects]
### Why #3: [system cause]
Evidence: [architecture, dependencies]
Impact: [broader implications]
### Why #4: [process/design cause]
Evidence: [patterns, decisions]
Impact: [long-term effects]
### Why #5: [root cause]
Evidence: [fundamental issue]
Impact: [core problem]
3. Identify Root Cause
Document the fundamental issue requiring attention:
## Root Cause Identified
[the fundamental issue that needs addressing]
## Recommended Investigation Areas
- specific files to examine
- components to test
- systems to verify
Investigation Principles
- Avoid solution bias - focus on understanding before fixing
- Gather evidence - don't assume, verify with data
- Consider multiple causes - issues often have multiple contributing factors
- Document findings - clear documentation prevents repeat issues
- Think systemically - consider broader implications
- Question assumptions - challenge "it should work" thinking
- Use version control - check when issue was introduced
Using Reference Materials
Load reference files as needed during investigation:
- references/patterns.md - common root cause patterns by category (configuration, race conditions, resource exhaustion, integration failures, build/deployment issues)
- references/techniques.md - investigation techniques with command examples (error analysis, code investigation, dependency analysis, environment investigation)
Best Practices
- resist proposing solutions until root cause is identified
- be thorough and methodical
- document evidence at each level of analysis
- verify assumptions with concrete data
- consider the issue from multiple perspectives (technical, environmental, architectural, external dependencies, process)
The goal is to find the fundamental cause, not just fix symptoms.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/umputun/cc-thingz/root-cause-investigator">View root-cause-investigator on skillZs</a>