Content
61%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 is a well-organized overview with a genuine Check/Fix workflow and a properly signaled one-level reference file. Its weaknesses are redundancy (a verbatim-duplicated CLS paragraph and an Explain section covering what Claude already knows), no inline before/after HTML despite the Fix section requiring it, and verification appearing only as an implicit mention.
Suggestions
Cut the "Explain" section and the duplicated CLS threshold paragraph — Claude already knows this; keep one pointer to the reference's rationale instead.
Add one inline before/after HTML snippet in the Fix section so the demanded output format is demonstrated in the body, or point explicitly to the reference's Code Examples section for it.
Make verification an explicit step in the workflow (e.g. "Verify: enable Layout Shift Regions in DevTools and confirm no movement after the fix") rather than a side mention in the Code Review section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The intro explains CLS thresholds ("A CLS score above 0.1 is considered 'needs improvement'") and the entire "Explain" section teaches browser placeholder behavior Claude already knows ("when a browser parses HTML, it does not yet know an image's dimensions"), while Quick Reference bullets duplicate Fix steps ("Pair with height: auto", "do not set arbitrary"). Mostly efficient, but the unnecessary explanation and duplication mean it could be tightened. | 3 / 5 |
Actionability | Concrete, executable guidance exists ("Report each image missing dimensions with its file path and line number", "width=\"800\" height=\"450\"", "CSS max-width: 100% and height: auto", "use the CSS aspect-ratio property as a fallback") with an explicit low-risk example ("<img src=\"/divider.svg\" alt=\"\" aria-hidden=\"true\">"). The minor gap is that the demanded before/after HTML output has no inline example — all full snippets live in the reference file — which fits mostly-executable guidance with minor gaps rather than the pseudocode/missing-details anchor below. | 4 / 5 |
Workflow Clarity | The Check → Fix → Explain → Code Review sequence is present and Fix is numbered 1–5 with skip conditions, but verification is only a side mention ("describe how to confirm the fix in DevTools") rather than an explicit checkpoint in the flow — checkpoints are implicit, matching the anchor for steps listed with validation gaps. | 3 / 5 |
Progressive Disclosure | The bundle structure is sound: the body is a sectioned overview and "see `references/rule.md`" points to an existing file one level deep, clearly signaled at the end. However, the body's intro paragraph is duplicated verbatim in the reference's "Why It Matters" and the Explain section overlaps the reference's "How Browsers Use These Attributes", a minor organization gap that keeps it from a clean split. | 4 / 5 |
Total | 14 / 20 Passed |