Content
71%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 a dense, fluff-free operator manual with copy-paste commands, explicit validation checkpoints, and genuine progressive disclosure to reference files. It is held back by repeated explanations of the same rules across sections and by heavy citation of schema files that are absent from the bundle, which breaks navigation to most of the detailed material.
Suggestions
Fix the reference paths: schemas/renders.md, schemas/repo-toml.md, and schemas/validators.md are cited ~12 times but do not exist in the bundle (validators.md lives at references/) — either ship the schemas/ files or repoint the links so the routing, key, and marker-semantics detail is reachable.
Deduplicate the AGENTS.md-region and severity-routing explanations that appear in both 'What reads what' and 'The pieces'/'The doctrine lives in one file per repo', keeping one canonical statement and one pointer.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every sentence carries a rule with no concept explanations Claude already knows ("Exit codes: 0 clean, 1 findings, 2 could not complete"), but material repeats across sections — the AGENTS.md region rules in 'The pieces' reappear in 'The doctrine lives in one file per repo', and severity routing is explained both in 'What reads what' note (b) and again in the canary paragraph — so a trim pass remains. Anchor 4 ('efficient, minor instances that could be trimmed'), not 5, because of that repetition and the dense edge-case run in the '--output local' paragraph. | 4 / 5 |
Actionability | The verb block is copy-paste ready with inline comments ("bot-instructions render # write every enabled surface" plus check, adopt, retire), flags and exit codes are enumerated, and there is a concrete migration sequence ("A repo without the heading adds it, sets `[bot-instructions.bots] codex`, runs `adopt`, then `render`"). It falls short of anchor 5 because common flows never show the exact TOML to write, and much executable detail sits behind schema references that do not resolve in this bundle. | 4 / 5 |
Workflow Clarity | Sequences exist with real validation checkpoints for batch file writes: render "writes every enabled surface after validating it", check "re-renders and diffs", adopt --dry-run "reports the content to take over and its divergence, writes no marker", and drift handling names each verb's finding. It is anchor 4 rather than 5 because the recovery action after a nonzero exit code is left implicit and the main flows are scattered across prose sections instead of one ordered workflow with feedback loops. | 4 / 5 |
Progressive Disclosure | The overview/reference split is real and well signaled — vendor caps in references/limits.md and the add-a-repo sequence in references/checklist.md exist and are one level deep — but the body's most-cited detail files (schemas/renders.md, schemas/repo-toml.md, schemas/validators.md — roughly 12 links) do not exist at those paths in the bundle (a validators.md exists under references/ instead), so navigation to the routing, key, and marker-semantics detail breaks. Some structure with a significant navigation gap: anchor 3, not 4. | 3 / 5 |
Total | 15 / 20 Passed |