Content
70%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 highly actionable body with an excellent validate-and-retry workflow, undermined by notable redundancy — the mandatory tool-call workflow is repeated three times — and by large inline reference catalogs (components, targets, APIs) that should live in separate files under references/.
Suggestions
State the search/write/validate/retry workflow once in the numbered 'Required Tool Calls' section and delete the two duplicated 'MANDATORY' sections, keeping only error-recovery details not already covered.
Move the ~90-line component example catalog and the extension target/API lists into references/ files (e.g. references/components.md, references/targets.md) and link to them from the body.
Remove the embedded system-prompt text ('You are an assistant that helps Shopify developers...') and the duplicated privacy notices — consolidate to one — since they consume context without adding actionable guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The search-then-validate workflow is stated three separate times ('Required Tool Calls', 'MANDATORY: Search Before Writing Code', 'MANDATORY: Validate Before Returning Code'), an ~90-line component example catalog and ~90-line target list are inlined, and embedded system-prompt filler ('You are an assistant that helps Shopify developers...') pads the file — several unnecessary or duplicated sections. | 2 / 5 |
Actionability | Everything is executable: an exact scaffold command (shopify app generate extension...), exact script invocations with every instrumentation flag explained, complete component examples showing all props, and prescriptive attribute rules with correct/incorrect examples. | 5 / 5 |
Workflow Clarity | The sequence is explicit with validation checkpoints and a genuine feedback loop: search, write, validate (mandatory, --target required), then on failure read the error, search for the type, fix, and re-validate up to 3 retries before returning code. | 5 / 5 |
Progressive Disclosure | Section headers exist and the referenced scripts (scripts/search_docs.mjs, scripts/validate.mjs) are real bundle files invoked directly, but the large component catalog and extension-target/API lists are inline content that belongs in separate reference files, and no references/ files exist to move them to. | 3 / 5 |
Total | 15 / 20 Passed |