Content
80%Weight 40%Scale 1-3Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is highly actionable and token-efficient, with concrete code and clear step sequencing for queries and mutations. The main gaps are the absence of an explicit validation/verification checkpoint after codegen and the lack of progressive disclosure into separate reference files for its several distinct topics.
Suggestions
Add an explicit validation step after "npm run gql:typegen" (e.g., confirm the .generated.ts file exists and re-run on error) to turn each workflow into a validate-and-retry loop.
Move deeper material such as fetch-policy details, optimistic-update guidance, and fragments into separate reference files (e.g., REFERENCE.md) linked from the main sections to apply progressive disclosure.
Add a brief note on how to verify a generated hook works (e.g., import resolves, types are present) so the multi-step workflows have a concrete success check.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and efficient: it avoids explaining what GraphQL or Apollo is and jumps straight to rules, file structure, and executable code, with every section earning its tokens. | 3 / 3 |
Actionability | It provides fully executable, copy-paste-ready code (real .gql files, "npm run gql:typegen", complete React hook usage) plus concrete WRONG/CORRECT anti-pattern comparisons and specific commands. | 3 / 3 |
Workflow Clarity | Query and mutation creation are sequenced as Step 1/2/3, but there is no explicit validation checkpoint (e.g., confirm the .generated file was produced or handle codegen failure) after running codegen. | 2 / 3 |
Progressive Disclosure | The document is a single self-contained ~290-line file with no bundle files; while well-organized by section, several topics (fragments, optimistic updates, fetch policies) that could live in separate reference files are kept inline. | 2 / 3 |
Total | 10 / 12 Passed |