Content
63%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, short overview with excellent progressive disclosure — a clearly signaled, verified one-level reference in references/rule.md. However, it suffers from internal duplication (Quick Reference vs. Fix vs. Explain), padding that explains concepts Claude already knows, and body-level guidance that names tools (validator.w3.org, html-validate) without any executable command or example.
Suggestions
Deduplicate the common-issues list: it appears nearly verbatim in both Quick Reference and Fix — keep it in one place and drop the other.
Remove or drastically trim the opening rationale sentence and the Explain section, since 'why invalid HTML is bad' is knowledge Claude already has and adds token cost without new information.
Add one executable inline command (e.g., a concrete html-validate invocation for CI/CD) so the Fix section is actionable without opening references/rule.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly brief, but includes removable material: the rationale sentence "Invalid HTML causes unpredictable rendering across browsers, breaks accessibility tools, and makes debugging significantly harder" explains consequences Claude already knows; "Common issues: unclosed tags, invalid nesting, missing attributes" (Quick Reference) is duplicated nearly verbatim in Fix ("fix reported errors including unclosed tags, missing attributes, and invalid nesting"); and the Explain section reiterates why validation matters. Not a 4: there are several instances of duplication and known-concept padding; not a 2: the body is short overall with no tutorial-style prose. | 3 / 5 |
Actionability | Some concrete guidance exists — "Use validator.w3.org or browser extensions", "Integrate validation into CI/CD with html-validate", and specific error types — but there are no executable commands or code in the body (e.g., an actual html-validate invocation), and "Run HTML through W3C validator and fix reported errors" is a high-level instruction rather than an executable step. Not a 4: nothing in the body is copy-paste ready, even though the deferred references/rule.md likely contains it; not a 2: specific tools and concrete error classes are named. | 3 / 5 |
Workflow Clarity | The Check → Fix → Explain → Code Review sections give a clear sequence, and "Fix errors first, then warnings (errors cause rendering issues)" is an explicit prioritization checkpoint. Not a 5: the workflow implies fixing but never states a re-validate-after-fixing feedback loop (the fix/verify loop is implicit), so the checkpoint coverage is incomplete; not a 3: the sequence is clear and a prioritization rule is stated. | 4 / 5 |
Progressive Disclosure | The body is a concise overview that clearly signals a single one-level-deep reference: "For full implementation details, code examples, and framework-specific guidance, see `references/rule.md`" — and that file exists in the bundle with substantive content (673 lines including code examples). Sections are well-organized and navigation is trivial, matching the 5 anchor. | 5 / 5 |
Total | 15 / 20 Passed |