Content
67%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 presents a well-structured Check/Fix/Explain workflow with concrete numbered steps and a clean one-level pointer to references/rule.md, which genuinely holds the deeper material. Its main weaknesses are the verbatim duplication of the reference's rationale paragraph, an Explain section re-teaching HTML semantics Claude already knows, and the absence of a post-fix validation step.
Suggestions
Drop the duplicated opening paragraph — it appears verbatim in references/rule.md's "Why It Matters"; keep the body's opening to the Quick Reference or a one-line summary.
Trim the "Explain" section's re-teaching of figure/figcaption semantics (Claude already knows these) and keep only the screen-reader consequence specific to this rule.
Add a post-fix validation step to the Fix workflow (e.g., "re-run the Check conditions on each changed image; see the Verification section of references/rule.md for tooling").
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The opening paragraph ("Using a <p> tag as a caption is invisible to assistive technology...") duplicates references/rule.md's "Why It Matters" section verbatim, and the "Explain" section re-teaches figure/figcaption semantics Claude already knows ("The <figure> element represents self-contained content... that could be moved without affecting the document flow"). These are more than minor over-explanations, so anchor 3 fits better than 4. | 3 / 5 |
Actionability | The Check and Fix sections give concrete numbered steps ("Verify: 1) Such image-caption pairs are wrapped in <figure>... 4) The alt text on the <img> is not identical"; "1) Wrap the <img> and its caption text in a <figure> element"), which is directive and specific. Not 5 because no good/bad markup example appears inline — all code examples are deferred to the reference; not 3 because the guidance is concrete, not pseudocode. | 4 / 5 |
Workflow Clarity | The Check → Fix → Explain → Code Review sequence is clear with explicit numbered verification conditions acting as checkpoints. It falls short of 5 because there is no post-fix re-validation step in the body workflow — the reference file's Verification section is never surfaced in the body. | 4 / 5 |
Progressive Disclosure | The body is a concise overview with a clearly signaled, one-level-deep pointer ("For full implementation details, code examples, and framework-specific guidance, see references/rule.md") and the referenced file exists and delivers exactly that. Not 5 because the duplicated "Why It Matters" paragraph blurs the split between overview and reference content. | 4 / 5 |
Total | 15 / 20 Passed |