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.
The content is a dense, well-structured operations manual with concrete paths, exact tags/paths, and clear numbered workflows including verification steps. It is strong on actionability and workflow clarity, with only minor conciseness and progressive-disclosure improvements available around repeated revalidation lists and missing Convex code examples.
Suggestions
Consolidate the revalidation tag/path set (currently repeated in 'publish article', 'Adding a New Post', and the publish step) into one canonical block or a referenced file to reduce length and drift risk.
Add one copy-paste Convex upsert snippet (e.g., contentResources.upsert with resourceId, type, fields.draft) so the 'write article' workflow is fully executable rather than described.
Move the full MDX frontmatter field reference into a separate file (e.g., references/frontmatter.md) and keep only the essential field notes inline, improving progressive disclosure and conciseness.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is largely lean and assumes Claude's competence (e.g., exact YAML field shapes, regex one-liners, file/purpose tables) with little padding, though sections like the full frontmatter example and repeated revalidation tag/path lists across three sections add some length that could be tightened via a shared reference. | 4 / 5 |
Actionability | Guidance is mostly executable: specific file paths, exact revalidate tags/paths, a copy-ready MDX frontmatter block, and a concrete regex. Minor gaps are the absent Convex upsert code sample and the un-illustrated <YouTube id="..." /> usage, which keep it just below fully copy-paste ready. | 4 / 5 |
Workflow Clarity | The hard-trigger workflows ('write article', 'publish article', 'Adding a New Post') are clearly numbered with a final verification step (check homepage/slug/markdown twin/feed consistency), providing good checkpoints; the only gap is no explicit validate-then-retry loop after the revalidate POST, so it sits just below the 5 anchor. | 4 / 5 |
Progressive Disclosure | The body is well-organized into clear headed sections (OPSEC, Content Model, Hard Trigger Workflow, Design System, Key Files, Network Page) and points to real bundle scripts (scripts/seed-articles.ts, scripts/seed-adrs-discoveries.ts) one level deep; it is slightly below 5 because some referenceable detail (the revalidation tag/path set, the full MDX frontmatter) is inlined and repeated rather than split out. | 4 / 5 |
Total | 16 / 20 Passed |