Content
63%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.
A dense, well-sectioned body with genuinely actionable commands, exact schema field rules, and explicit validation with error-recovery guidance. Its weaknesses are duplication (commands and fallback logic repeated across sections, routing metadata duplicated from the description), no inline example of the core output artifact, and a References section where most pointed-to files are missing from the bundle.
Suggestions
Consolidate the duplicated command listings ("Canonical command path" vs "Quick Reference") and describe the knows.academy→OpenAlex→Semantic Scholar fallback in one place only.
Include a minimal example `.knows.yaml` sidecar (or a skeleton with the exact top-level keys, statement/evidence/relation shape, and confidence/coverage objects) inline so Generate mode does not depend solely on the external spec file.
Fix or ship the referenced bundle files — `resources/sidecar-spec.md`, `resources/execution-protocol.md`, `resources/checklist.md`, and the other `resources/*.md` paths are cited multiple times but absent from the bundle, breaking navigation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body avoids explaining known concepts, but it is noticeably repetitive and could be tightened: the same `oma scholar search|resolve|get` commands appear in both "Canonical command path" and "Quick Reference", the provider fallback is described in four places (Transitions, Guardrails, "Provider Fallback", Troubleshooting), and the "Scheduling" block restates routing info already in the description and Modes table. Time-sensitive specifics ("only 2026 papers", v0.9.0, the 47% dangling-ref stat) sit inline rather than in a versioned/deprecated section. This matches "mostly efficient but includes some unnecessary explanation or could be tightened"; too much duplication for a 4. | 3 / 5 |
Actionability | Concrete, executable guidance throughout: exact CLI invocations with flags (`oma scholar lint --fail-on-warning paper.knows.yaml`), raw curl endpoints, exact field names (`statement_type`, `evidence_type`), ID format examples, and an error-message-to-fix troubleshooting table. Not a 5 because the primary Generate mode never shows an example `.knows.yaml` sidecar and defers the artifact format to `resources/sidecar-spec.md`, which is absent from the provided bundle — a real gap for the most common case. | 4 / 5 |
Workflow Clarity | A clear PREPARE→ACQUIRE→REASON→ACT→VERIFY→FINALIZE sequence is present with an explicit validation step ("run lint before sharing", guardrail 13) and feedback loops (failure/recovery section plus an error→fix troubleshooting table with retry guidance). It falls short of a 5 because per-mode numbered execution steps are delegated to `resources/execution-protocol.md`, which is not present in the bundle, leaving the concrete step order for each mode implicit. | 4 / 5 |
Progressive Disclosure | Section structure is good and the References list clearly labels each file with its purpose at one level deep, but scored against the actual bundle, 9 of the 11 referenced paths do not exist (all `resources/*.md`, `cli/commands/scholar/`, `config/scholar-config.yaml`, `../../rules/i18n-guide.md`); only the two `references/_shared/core/` files are present. Navigation to the spec, checklist, and protocol files is broken in the provided bundle, and much of the shared `references/_shared/` content is never referenced — better than minimal structure, but the broken reference paths are more than the minor organization gaps of a 4. | 3 / 5 |
Total | 14 / 20 Passed |