Content
78%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.
The body is highly actionable and efficient, with excellent tables, code, and a validated 8-step workflow. Its main defect is that the progressive-disclosure layer is broken: every reference file cited in the Reference section is absent from the bundle, so the detailed patterns it defers to are unreachable.
Suggestions
Create the missing reference files the body cites — reference/scorer-patterns.md, reference/api-reference.md, reference/flag-schema-guide.md, and reference/templates/ — or remove the Reference section until they exist, since every detailed-pattern and type-signature lookup currently dead-ends.
Add an explicit fix-and-retry loop to the Workflow section (e.g., "if eval-validate reports errors, fix them and re-run before scaffolding coverage") so error recovery is part of the sequence rather than only implied by the Common Pitfalls table.
Trim the Philosophy section and its restated points (e.g., "Data drives coverage") since the Data Design Guidelines table already conveys them concretely.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and SDK-specific — tables, exact import paths, and commands dominate, with no generic-concept padding (it never explains what evals or SDKs are in the abstract). Minor trimming is possible: the "Philosophy" section ("Evals are tests for AI. Every eval answers: 'does this capability still work?'") and the "Data drives coverage" prose restate points made concretely elsewhere, which keeps it below anchor 5. | 4 / 5 |
Actionability | Guidance is fully executable: a copy-paste-ready Eval file template with exact import paths (`import { Eval } from 'axiom/ai/evals'`), an onlineEval signature, a complete CLI command table, per-script usage examples (e.g., `eval-scaffold classification support-agent categorize`), and a pitfalls table mapping exact error strings to fixes. This matches anchor 5's copy-paste-ready standard with common cases covered. | 5 / 5 |
Workflow Clarity | The Workflow section gives a clear 8-step sequence with concrete commands and explicit validation checkpoints (validate structure, analyze coverage gaps, `--debug` local run before deploy), plus a separate 4-step "How to Start" process. It stops short of anchor 5 because the feedback loops are not wired into the workflow itself — there is no "if validation fails, fix and re-run" step, only an indirect error-recovery mapping in the Common Pitfalls table. | 4 / 5 |
Progressive Disclosure | The Reference section is clearly signaled and one level deep ("read these on demand" with per-file descriptions), which would score 5 — but scoring against the actual bundle, all four referenced paths (`reference/scorer-patterns.md`, `reference/api-reference.md`, `reference/flag-schema-guide.md`, `reference/templates/`) do not exist; only the scripts directory is present and its references check out. Dangling references mean the promised detail layer is entirely missing, which is worse than anchor 4's "minor organization gaps" and leaves the structure well-intentioned but functionally broken. | 3 / 5 |
Total | 16 / 20 Passed |