How do I install the Root Cause Investigation skill?

Run npx skillmds@latest add onedro1d/root-cause-investigation in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Root Cause Investigation safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Root Cause Investigation?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Root Cause Investigation free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Root Cause Investigation?

OneDro1d (@onedro1d) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Root Cause Investigation by onedro1d

Name: Root Cause Investigation
Author: OneDro1d

Root Cause Investigation

Turn a symptom into a confirmed root cause using evidence, not guesses — across any service, DB, queue, API, or infra. Use for "find the bug", "why is this failing", "0 records / stuck / DLQ / timeout / wrong data". Checks known findings first; escalates when evidence is missing instead of assuming.

OneDro1d ccf9aaa 2.0 KB Updated Sep 17, 2026

File contents

Root-Cause Investigation (evidence-first)

Goal: fast, correct root cause with minimum tokens. A plausible guess is worse than "need more evidence."

Procedure

Check memory: .claude/context/FINDINGS.md — if already root-caused, reuse it and stop.
Locate: use SERVICE-MAP + the relevant <service>/CLAUDE.md to find where the symptom lives.
Trace: follow the flow (dependency-mapping) to the component where expected ≠ actual.
Gather evidence before concluding: the exact file:line, the data/log/state that proves it, and what you ruled out.
Confirm the mechanism: state precisely why the code produces the symptom (e.g. "reads a scope column the copy path never writes → 0 rows").
Escalate, don't guess: if you can't confirm in code/data, list the missing evidence and what would resolve it.

Common failure modes to check first

Silent zero-records (record-element detection / stale build).
Object-store key drift writer↔reader (consumer requeues forever).
Stale container / non-regenerated artifact (silent).
Secondary store write inside the primary DB txn → timeout under load.
Restricted/non-restricted data misroute (fail-safe default).
Poison vs transient Nack misclassification (dead-letter vs infinite requeue).

Output → Root Cause Analyzer / user

SYMPTOM: <observed>
ROOT CAUSE: <one sentence, mechanism>
EVIDENCE: <file:line, data/log, what was ruled out>
BLAST RADIUS: <other flows/services affected>
FIX OPTIONS: <1-3, no code> | CONFIDENCE: high/med/low
UNKNOWNS: <missing evidence, if any>

Confirmed causes get written to FINDINGS.md (via knowledge-keeper).

---name: root-cause-investigationdescription: Turn a symptom into a confirmed root cause using evidence, not guesses — across any service, DB, queue, API, or infra. Use for "find the bug", "why is this failing", "0 records / stuck / DLQ / timeout / wrong data". Checks known findings first; escalates when evidence is missing instead of assuming.---# Root-Cause Investigation (evidence-first)Goal: fast, correct root cause with minimum tokens. A plausible guess is worse than "need more evidence."## Procedure1. **Check memory**: `.claude/context/FINDINGS.md` — if already root-caused, reuse it and stop.2. **Locate**: use SERVICE-MAP + the relevant `<service>/CLAUDE.md` to find where the symptom lives.3. **Trace**: follow the flow (dependency-mapping) to the component where expected ≠ actual.4. **Gather evidence** before concluding: the exact `file:line`, the data/log/state that proves it, and what you ruled out.5. **Confirm the mechanism**: state precisely *why* the code produces the symptom (e.g. "reads a scope column the copy path never writes → 0 rows").6. **Escalate, don't guess**: if you can't confirm in code/data, list the missing evidence and what would resolve it.## Common failure modes to check first- Silent zero-records (record-element detection / stale build).- Object-store key drift writer↔reader (consumer requeues forever).- Stale container / non-regenerated artifact (silent).- Secondary store write inside the primary DB txn → timeout under load.- Restricted/non-restricted data misroute (fail-safe default).- Poison vs transient Nack misclassification (dead-letter vs infinite requeue).## Output → Root Cause Analyzer / user```SYMPTOM: <observed>ROOT CAUSE: <one sentence, mechanism>EVIDENCE: <file:line, data/log, what was ruled out>BLAST RADIUS: <other flows/services affected>FIX OPTIONS: <1-3, no code> | CONFIDENCE: high/med/lowUNKNOWNS: <missing evidence, if any>```Confirmed causes get written to FINDINGS.md (via knowledge-keeper).

Frequently asked questions