Content
71%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-structured, actionable rule evaluation with excellent progressive disclosure — concrete detection criteria, three specific fix paths, and a verified one-level-deep reference holding the code examples and verification details. Its main weakness is redundancy: screen-reader rationale is explained twice, Quick Reference bullets restate other sections, and the Code Review section is generic boilerplate that could be cut or made rule-specific.
Suggestions
Merge the opening paragraph into the Explain section — both cover screen-reader announcement loss ('NVDA and JAWS will not say list of 5 items', 'announce the list type and the total item count').
Trim the Quick Reference bullets that restate Check/Explain content, keeping only the parent-element rule and the ARIA ownership requirement once.
Replace the generic Code Review boilerplate ('Flag exact elements, roles, labels, focus behavior, or keyboard interactions...') with rule-specific review guidance, or fold it into Check and cite references/rule.md's Verification section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient and contains non-obvious, valuable specifics (NVDA/JAWS/VoiceOver announcement behavior, the 'list-style: none' semantics-stripping caveat), but it has real duplication: the intro paragraph and the Explain section both cover screen-reader announcement loss, the Quick Reference bullets restate rules already given in Check and Explain ('Similarly, role='listitem' must be owned by a role='list''), and the Code Review section is generic boilerplate applicable to any accessibility rule ('Flag exact elements, roles, labels, focus behavior, or keyboard interactions... browser accessibility tooling'). This matches anchor 3 — some unnecessary explanation that could be tightened — rather than 4, where over-explanation would be only minor. | 3 / 5 |
Actionability | The Check section is a concrete, executable procedure ('check that its direct parent element is `<ul>`, `<ol>`, or `<menu>`. Flag any `<li>` whose parent is `<div>`, `<section>`, `<nav>`, `<span>`...') and Fix gives three specific, numbered remediation paths with exact replacement elements. This matches anchor 4; not 5 because the body contains no code examples (deferred to references/rule.md) and one check is slightly vague ('their closest ancestor with a list-related role'), and not 3 because the guidance is genuinely concrete rather than pseudocode-level. | 4 / 5 |
Workflow Clarity | The Check → Fix → verify sequence is clear and the single evaluation task is unambiguous, with verification pointed to in the Code Review section ('note how to verify the fix with browser accessibility tooling or assistive tech'). This matches anchor 4: clear sequence with most checkpoints present but a minor validation gap — the body's verification is generic, with the concrete checks (axe, Lighthouse, keyboard testing) deferred to references/rule.md. Not 5 because the in-body validation checkpoint is not explicit or specific; not 3 because the sequence is coherent and checkpoints are present. | 4 / 5 |
Progressive Disclosure | The ~30-line body is well organized into Quick Reference, Check, Fix, Explain, and Code Review sections, keeps code examples and detailed verification appropriately out of the main file, and clearly signals a single one-level-deep reference ('For full implementation details, code examples, and framework-specific guidance, see `references/rule.md`') — a file verified to exist and to contain exactly that deferred content. This matches anchor 5: clear overview with well-signaled one-level-deep references and appropriately split content. | 5 / 5 |
Total | 16 / 20 Passed |