Content
40%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 concise and well-sectioned but hollow: the workflow is four abstract directives with no concrete, executable guidance, and progressive disclosure is broken — it points to a nonexistent 'resources/implementation-playbook.md' while leaving the four substantial bundle files (REST best practices, GraphQL schema design, an API checklist, and a FastAPI template) entirely unlinked. The main fixes are to correct the reference path to the real files and to make each instruction step concrete.
Suggestions
Fix the broken reference: replace "resources/implementation-playbook.md" with the actual bundle paths (references/rest-best-practices.md, references/graphql-schema-design.md, assets/api-design-checklist.md, assets/rest-api-template.py), each with a one-line description of when to consult it.
Make the four instruction steps actionable — e.g., 'List consumers and their use cases', 'Prefer REST for resource-centric CRUD, GraphQL for client-driven querying', 'Specify error format (RFC 9457 problem details), cursor pagination, and versioning strategy' — or inline one short concrete example per step.
Add an explicit validation checkpoint after step 3, e.g., 'Review the spec against assets/api-design-checklist.md before implementation', to give the workflow a real feedback loop instead of the implicit 'Validate with examples'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean — it assumes Claude's knowledge, explains no basic concepts, and uses tight sectioning (Use when / Do not use when / Instructions / Resources / Limitations). Minor trimmable redundancy keeps it below anchor 5: the frontmatter description sentence is repeated verbatim under the H1, the reference to the playbook is stated twice (in Instructions and again in Resources), and the Limitations boilerplate adds little. | 4 / 5 |
Actionability | The Instructions are high-level hints — "Define consumers, use cases, and constraints" and "Choose API style and model resources or types" — with no concrete commands, examples, decision criteria, or code in the body; the promised detail lives in a reference file. This matches 'minimal concrete guidance; high-level hints but missing the specific steps to execute' — above anchor 1 only because the steps do name specific concerns (errors, versioning, pagination, auth) that narrow the direction. | 2 / 5 |
Workflow Clarity | A rough four-step sequence exists (define → choose → specify → validate) but each step is a single vague directive with no expansion, and validation is only the implicit 'Validate with examples and review for consistency' with no checkpoints or error-recovery guidance. This is 'rough sequence present but many gaps; steps poorly defined; validation absent' — short of anchor 3, whose example steps are concrete and include a real test step. | 2 / 5 |
Progressive Disclosure | The body's only reference, "resources/implementation-playbook.md", does not exist in the bundle, while the four real bundle files (references/rest-best-practices.md, references/graphql-schema-design.md, assets/api-design-checklist.md, assets/rest-api-template.py) are never mentioned — so navigation to the actual detailed material is broken and those files are undiscoverable. Section structure itself is good, keeping this above anchor 1, but the incorrect reference path and completely unsurfaced bundle content fit 'minimal structure; references are buried' rather than anchor 3's 'references present but not clearly signaled'. | 2 / 5 |
Total | 10 / 20 Passed |