Content
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-organized overview that uses progressive disclosure correctly by deferring executable detail to a single real reference file. Its weaknesses are repeated explanation of the shadow-DOM/ElementInternals concept, no inline executable example, and validation steps that are signaled only in the reference rather than the body.
Suggestions
Remove the redundancy between the intro paragraph, the 'shadow DOM does not automatically expose ARIA' Quick Reference bullet, and the Explain section — state the shadow-DOM/ElementInternals bridge once.
Add a minimal inline code snippet to the Fix section (e.g. attachInternals() + ariaRole/ariaChecked reflection in the constructor) so the body is directly actionable without opening rule.md.
Add an explicit verification checkpoint to the body (e.g. 'after fixing, run axe DevTools and a keyboard-only tab-through; confirm zero critical ARIA violations') rather than deferring all validation to rule.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean, but the shadow-DOM/ElementInternals-bridge concept is restated across the intro paragraph, the Quick Reference bullet, and the Explain section, so it could be tightened rather than earning the 'every token earns its place' top anchor. | 2 / 3 |
Actionability | The Fix and Code Review sections name concrete APIs (ElementInternals.ariaRole, ariaLabel, formAssociated, roving tabindex) and specific keys, but the body itself contains no executable code and defers all copy-paste examples to references/rule.md, matching 'concrete guidance but incomplete for direct execution.' | 2 / 3 |
Workflow Clarity | The Check → Fix → Explain → Code Review structure gives a recognizable review sequence, but validation checkpoints (axe DevTools, keyboard-tab, screen-reader verification) live in rule.md rather than the body, leaving checkpoints implicit per the level-2 anchor. | 2 / 3 |
Progressive Disclosure | The body is a concise overview (Quick Reference, Check, Fix, Explain, Code Review) that clearly signals one real, one-level-deep reference — 'see references/rule.md' — which exists and holds the full details rather than chaining onward. | 3 / 3 |
Total | 9 / 12 Passed |