How do I install the Root Cause Analysis skill?

Run npx skillmds@latest add tomevault-io/root-cause-analysis-2 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 Analysis safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Root Cause Analysis?

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 Analysis free to use?

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

Who published Root Cause Analysis?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Root Cause Analysis by tomevault-io

Name: Root Cause Analysis
Author: tomevault-io

Root Cause Analysis

Analyze telemetry data for root cause analysis using Kopai CLI. Use when debugging errors, investigating latency issues, tracing request flows across services, or correlating logs with traces. Also use when users report production issues like "why is my API slow", "getting 500 errors", "service is down", "requests are timing out", or any symptom that needs telemetry-based investigation — even if they don't mention traces or observability explicitly. Use when this capability is needed.

tomevault-io Updated Sep 17, 2026

File contents

Root Cause Analysis with Kopai

Guide for debugging production issues using telemetry data (traces, logs, metrics) via Kopai CLI.

Prerequisites

Ensure access to Kopai app backend. Make sure the services are set up to send their OpenTelemetry data to Kopai. See otel-instrumentation skill for setup.

RCA Workflow

Find error traces — npx @kopai/cli traces search --status-code ERROR --limit 20 --json. If empty: broaden time range, check service name, or search logs with --severity-min 17
Get full trace context — npx @kopai/cli traces get <traceId> --json. Check Duration, StatusCode, and span hierarchy for bottlenecks
Correlate logs — npx @kopai/cli logs search --trace-id <traceId> --json. Look for error messages, stack traces, and timestamps
Check metrics — npx @kopai/cli metrics discover --json then npx @kopai/cli metrics search --type <type> --name <name> --json for anomalies
Present findings — summarize root cause with evidence (specific traceIds, log entries, metric anomalies), impact, and suggested fix

Quick Example

# Find failing requests
npx @kopai/cli traces search --status-code ERROR --service payment-api --json

# Get trace details (copy traceId from above)
npx @kopai/cli traces get abc123def456 --json

# Check correlated logs
npx @kopai/cli logs search --trace-id abc123def456 --severity-min 17 --json

Rules

1. Workflow (CRITICAL)

workflow-find-errors - Find Error Traces
workflow-get-context - Get Full Trace Context
workflow-correlate-logs - Correlate Logs with Trace
workflow-check-metrics - Check Related Metrics
workflow-identify-cause - Identify Root Cause & Present Findings

2. Patterns (HIGH)

pattern-http-errors - HTTP Error Debugging
pattern-slow-requests - Slow Request Analysis
pattern-distributed - Distributed Failure Tracing
pattern-log-driven - Log-Driven Investigation

Read rules/<rule-name>.md for details.

Tips

Always use --json for programmatic analysis
Pipe to jq for filtering/aggregation
Start with errors, then trace backwards
Check span Duration to find bottlenecks
Correlate TraceId across traces, logs, metrics
Use --severity-min 17 instead of --severity-text ERROR to catch all error-level logs regardless of text casing. Fall back to --body "error" for errors logged at INFO or with no severity.

References

trace-filters - Trace search filter options
log-filters - Log search filter options
metric-filters - Metric search filter options

Converted and distributed by TomeVault — claim your Tome and manage your conversions.

---name: root-cause-analysis-2description: Analyze telemetry data for root cause analysis using Kopai CLI. Use when debugging errors, investigating latency issues, tracing request flows across services, or correlating logs with traces. Also use when users report production issues like "why is my API slow", "getting 500 errors", "service is down", "requests are timing out", or any symptom that needs telemetry-based investigation — even if they don't mention traces or observability explicitly. Use when this capability is needed.---# Root Cause Analysis with KopaiGuide for debugging production issues using telemetry data (traces, logs, metrics) via Kopai CLI.## PrerequisitesEnsure access to Kopai app backend.Make sure the services are set up to send their OpenTelemetry data to Kopai.See otel-instrumentation skill for setup.## RCA Workflow1. **Find error traces** — `npx @kopai/cli traces search --status-code ERROR --limit 20 --json`. If empty: broaden time range, check service name, or search logs with `--severity-min 17`2. **Get full trace context** — `npx @kopai/cli traces get <traceId> --json`. Check Duration, StatusCode, and span hierarchy for bottlenecks3. **Correlate logs** — `npx @kopai/cli logs search --trace-id <traceId> --json`. Look for error messages, stack traces, and timestamps4. **Check metrics** — `npx @kopai/cli metrics discover --json` then `npx @kopai/cli metrics search --type <type> --name <name> --json` for anomalies5. **Present findings** — summarize root cause with evidence (specific traceIds, log entries, metric anomalies), impact, and suggested fix## Quick Example```bash# Find failing requestsnpx @kopai/cli traces search --status-code ERROR --service payment-api --json# Get trace details (copy traceId from above)npx @kopai/cli traces get abc123def456 --json# Check correlated logsnpx @kopai/cli logs search --trace-id abc123def456 --severity-min 17 --json```## Rules### 1. Workflow (CRITICAL)- `workflow-find-errors` - Find Error Traces- `workflow-get-context` - Get Full Trace Context- `workflow-correlate-logs` - Correlate Logs with Trace- `workflow-check-metrics` - Check Related Metrics- `workflow-identify-cause` - Identify Root Cause & Present Findings### 2. Patterns (HIGH)- `pattern-http-errors` - HTTP Error Debugging- `pattern-slow-requests` - Slow Request Analysis- `pattern-distributed` - Distributed Failure Tracing- `pattern-log-driven` - Log-Driven InvestigationRead `rules/<rule-name>.md` for details.## Tips1. Always use `--json` for programmatic analysis2. Pipe to `jq` for filtering/aggregation3. Start with errors, then trace backwards4. Check span Duration to find bottlenecks5. Correlate TraceId across traces, logs, metrics6. Use `--severity-min 17` instead of `--severity-text ERROR` to catch all error-level logs regardless of text casing. Fall back to `--body "error"` for errors logged at INFO or with no severity.## References- [trace-filters](references/trace-filters.md) - Trace search filter options- [log-filters](references/log-filters.md) - Log search filter options- [metric-filters](references/metric-filters.md) - Metric search filter options---> Converted and distributed by [TomeVault](https://tomevault.io/claim/kopai-app) — claim your Tome and manage your conversions.

Frequently asked questions