Content
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
Well-structured and token-efficient with clean progressive disclosure to real reference files. The main gaps are the absence of executable commands and a missing validation feedback loop in the workflow.
Suggestions
Add executable commands to the Instructions (e.g., `npx @stoplight/spectral-cli lint openapi.yaml`, `oasdiff breaking base.yaml revised.yaml`, `ajv-cli validate -s schema.json`) so steps are copy-paste ready instead of descriptive.
Insert an explicit validation feedback loop after the linting and breaking-change checks — e.g., 'if errors are found, fix them and re-run validation; only generate the report once all errors are resolved' — to add the missing checkpoint.
Show how scripts/validate-schema.sh is invoked from the workflow, and trim the inline Examples scenarios that overlap with references/examples.md to remove redundancy.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and avoids explaining concepts Claude already knows (no definition of OpenAPI or linting); every section earns its place, matching the token-efficient anchor. | 3 / 3 |
Actionability | Steps name concrete tools and conventions (Spectral, oasdiff, camelCase, status 400/401/404/500), but no executable commands or code are given, leaving the guidance descriptive rather than copy-paste ready. | 2 / 3 |
Workflow Clarity | Eight steps are clearly sequenced, but there is no explicit validate→fix→re-validate checkpoint loop; per the batch-operation cap this cannot reach 3, and it is above the score-1 unclear anchor. | 2 / 3 |
Progressive Disclosure | A concise overview points to real one-level-deep references (implementation.md, errors.md, examples.md) and scripts/validate-schema.sh, all clearly signaled with no nested reference chains. | 3 / 3 |
Total | 10 / 12 Passed |