Content
75%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 strong, well-structured body: concrete repo-specific rules, a clearly gated workflow, and real one-level-deep bundle references. Weaknesses are minor — one broken copy command, validation steps not embedded in the workflow sequence, and some redundancy between the Philosophy, Anti-Patterns, and reference-listing sections.
Suggestions
Fix the Quick Commands copy line to the real template path ("cp assets/templates/REFERENCE-paper.yaml ...") or drop it, since step 4 already directs reading the template from assets/templates/REFERENCE-paper.yaml.
Wire validation into the workflow: add an explicit step after step 4 ("Run ./scripts/validate-reference-paper.sh references/<slug>.md; fix and re-run until it passes") and after step 8, instead of leaving validators only in Quick Commands.
Merge the "References" and "Reference Material" sections into one, and fold the two overlapping benchmark-number anti-patterns ("NEVER invent benchmark numbers" and "NEVER state an evaluation number without marking it as reported") into one to trim tokens.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly lean ("Keep language precise. Do not pad."), but trimmable: the Philosophy section restates anti-patterns, two benchmark-number anti-patterns overlap, "References" and "Reference Material" sections list the same artifacts, and a stray table-row comment sits inside the Quick Commands code block. Fits anchor 4 (efficient with minor trimmable instances), not 5 (every token earning its place). | 4 / 5 |
Actionability | Concrete grep/curl/validator commands, a slug format with examples, and a template-driven step 4 — but "cp templates/REFERENCE-paper.md references/<slug>.md" references a nonexistent path (the real file is assets/templates/REFERENCE-paper.yaml), so that command fails as written. Anchor 4 (mostly executable, minor gaps), not 3 (guidance goes well beyond pseudocode) or 5 (one command is broken). | 4 / 5 |
Workflow Clarity | Eight clearly sequenced steps with a duplicate-check gate (step 2) and a user-confirmation gate (step 7). However, the validators appear only in Quick Commands, not wired into the step sequence — no explicit 'validate after creating the file' checkpoint — so the 5 anchor's fully explicit validation chain is not met. | 4 / 5 |
Progressive Disclosure | All referenced bundle files exist (references/mcp-servers.md, references/reviewed-and-index-formats.md, both templates, schemas, validators), are one level deep, and are well signaled with a when-to-use table. The duplicated "References"/"Reference Material" listings are a minor organization gap — anchor 4, not 5. | 4 / 5 |
Total | 16 / 20 Passed |