CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

root-cause-analysis

Investigate and root-cause production issues from live OpenTelemetry telemetry (traces, logs, metrics) with the Kopai SDK in TypeScript code mode. Use this skill to debug errors and error-rate spikes, investigate latency/slowness and timeouts, trace requests across services, find failing or cascading services, and correlate logs to a trace — including vague symptom reports like 'why is my API slow', 'getting 500 errors', 'service is down', 'requests are timing out', or 'something is failing in prod', even when the user never says 'traces' or 'observability'. This analyzes existing telemetry to find a cause. Do NOT use it to add instrumentation (use otel-instrumentation), to build dashboards or visualizations (use create-dashboard), or to fix non-telemetry problems like failing CI, lint errors, unit tests, or SQL query tuning.

Quality

94%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

The canonical home for this skill is kopai/root-cause-analysis

SKILL.md
Quality
Evals
Security

Quality

Content

85%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

Strong, dense, highly actionable content: executable code throughout, non-obvious backend gotchas, and a well-sequenced RCA workflow with genuine validation checkpoints. Two flaws hold it back: repeated typed-rows/Quick-Example redundancy, and nine references to a `rules/` directory that does not exist in the bundle, breaking the disclosure path for workflow/pattern details.

Suggestions

Ship the `rules/` directory (workflow-find-errors.md, workflow-get-context.md, workflow-correlate-logs.md, workflow-check-metrics.md, workflow-identify-cause.md, pattern-http-errors.md, pattern-slow-requests.md, pattern-distributed.md, pattern-log-driven.md) or remove the "Read `rules/<rule-name>.md` for details" pointers and fold any essential detail inline — as written, nine references resolve to nothing.

Cut the redundancy: state "fully typed rows — never cast to any" once (the Code mode section) and drop its repetition in the query-snippet comment and Tip 3; replace the Quick Example (a near-verbatim duplicate of workflow step 1) with a variant that adds value, e.g. a log-correlation or metrics script.

Consolidate the StatusCode guidance: the "Unset" vs "Ok" gotcha appears in both Backend caveats and the CLI fallback; keep the full explanation in caveats and leave only a one-word cross-reference in the CLI section.

DimensionReasoningScore

Conciseness

Mostly lean and dense with genuinely non-obvious backend knowledge ("StatusCode is exactly \"Unset\" | \"Ok\" | \"Error\"", "On SQLite they fail at query time", "result rows report nanoseconds"), but there is repetition: "fully typed — rows autocomplete and typos are compile errors" appears three times (Code mode, the query snippet comment, and Tip 3), the StatusCode/Unset gotcha appears twice, and the Quick Example duplicates the workflow step-1 query almost verbatim. Anchor 4 fits — efficient with minor trimmable redundancy; not 3 because there is no explanation of concepts Claude already knows and no padding.

4 / 5

Actionability

Every stage has copy-paste-ready executable code: full typed TypeScript queries with exact imports, run command ("npx tsx rca.mts" with the .mts rationale and a tsx-missing fallback), install command ("npm i @kopai/sdk"), concrete filter syntax ("f.gte(\"SeverityNumber\", 17)", "f.gt(\"Duration\", \"1s\")"), error handling, and a CLI fallback with exact flags. Specific examples cover the common RCA cases (error ranking, trace context, log correlation, time-series onset).

5 / 5

Workflow Clarity

The RCA Workflow is a clearly sequenced 5-step process (find failing work → trace context → correlate logs → quantify impact → present findings), each with executable code. Validation/feedback loops are present: the empty-result checkpoint ("Before concluding 'no errors / no data', re-check the column name and value casing"), the try/catch with "KopaiQueryBuildError → e.issues" recovery pattern, and the retention-floor caution ("say so rather than calling the floor a 'step change'"). The operations are read-only queries, so the destructive/batch cap does not apply. Not 4 because checkpoints are explicit, not merely implied.

5 / 5

Progressive Disclosure

The main split is good — detailed column/filter reference lives in three real one-level-deep files clearly signaled in References ([trace-filters](references/trace-filters.md), [log-filters](references/log-filters.md), [metric-filters](references/metric-filters.md)) — but the body cites nine rule files (workflow-find-errors, workflow-get-context, workflow-correlate-logs, workflow-check-metrics, workflow-identify-cause, pattern-http-errors, pattern-slow-requests, pattern-distributed, pattern-log-driven) and instructs "Read `rules/<rule-name>.md` for details", and no `rules/` directory exists in the bundle. Scoring against the actual bundle structure, the primary detail-navigation for the workflow and patterns is broken (dead paths), which is more than the 'minor organization gaps' of anchor 4 but the inline content keeps each step self-sufficient, so above anchor 2.

3 / 5

Total

17

/

20

Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A model description: concrete capabilities, explicit when-to-use triggers including natural vague symptom phrasings, and explicit when-not-to-use boundaries that disambiguate sibling skills. Dense but every clause earns its place.

DimensionReasoningScore

Specificity

Lists multiple concrete actions — "Investigate and root-cause production issues from live OpenTelemetry telemetry (traces, logs, metrics)", "debug errors and error-rate spikes", "investigate latency/slowness and timeouts", "trace requests across services", "find failing or cascading services", "correlate logs to a trace" — comprehensive coverage of the RCA capability space. Not below 4 because coverage is broad and every action is concrete with no filler; the anchor-5 example shows the same shape.

5 / 5

Completeness

Explicitly answers both questions: what ("Investigate and root-cause production issues from live OpenTelemetry telemetry...") and when ("Use this skill to debug errors and error-rate spikes... including vague symptom reports like...") with concrete trigger phrases. It also adds explicit negative scope ("Do NOT use it to add instrumentation... to build dashboards... or to fix non-telemetry problems"), exceeding the anchor-5 example.

5 / 5

Trigger Term Quality

Comprehensive natural-language coverage: "debug errors", "latency/slowness and timeouts", "find failing or cascading services" plus quoted vague symptom reports — "why is my API slow", "getting 500 errors", "service is down", "requests are timing out", "something is failing in prod" — explicitly included for users who "never say 'traces' or 'observability'". These are exactly the phrases a real user would say, matching the anchor-5 synonym-inclusive example.

5 / 5

Distinctiveness Conflict Risk

Clear niche (telemetry-based RCA) with explicit disambiguation from adjacent skills — "use otel-instrumentation" for instrumentation, "use create-dashboard" for dashboards — and from non-telemetry debugging ("failing CI, lint errors, unit tests, or SQL query tuning"). Minimal conflict risk; no generic phrasing that would fire for unrelated skills.

5 / 5

Total

20

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

kopai-app/kopai-mono

Path

skills/root-cause-analysis/SKILL.md

Reviewed

Table of Contents

Is this your skill?

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.