Content
85%Weight 40%Scale 1-5Reviews 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.
| Dimension | Reasoning | Score |
|---|---|---|
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 |