Rubric: reader orientation
Written by a person. Last read by a person on 2026-09-05, 23 days ago. Its facts were checked by the eval suite on 2026-09-28.
Enforced by check_use_cases, check_levels_served and check_levels_serve_their_page.
The claim
A page says who it is for before it says anything else, and every reader level it names has something written for it on that page.
Observable evidence
- The
use_casesvalue in each page's frontmatter, and its length. - The levels declared in
data/levels.yaml, and the audiences each one names. - The audiences actually used by notes in
data/annotations/. - The levels each built page renders, and the
data-audiencevalues on the same page.
The pass bar
Every reader-facing page carries use_cases of at least twelve words. Every declared level
names at least one audience, and at least one note is addressed to it. Every level a page
offers is served by something on that page. At least one of them tells some notes from
others. A page whose notes are addressed to levels offers the levels.
Why this rubric exists
A reader who cannot tell in one paragraph whether a page is theirs will read three pages badly rather than one page well. The paragraph is also the cheapest diagnostic available for a page organized around its author's structure: use cases that are hard to write are usually hard because the page is about the wrong thing.
The second half is the one with teeth. Declaring a reader level costs nothing and promises somebody they are catered for. Leaving nothing addressed to them breaks that promise quietly, which is worse than never having made it, because the reader spends time looking for what was advertised before concluding it is them rather than the page.
Ambiguous cases
The rubrics are exempt, except their index. They are a reference sub-collection reached through one page that carries the use cases for all of them, and each opens with "Enforced by" and "The claim", which is this rubric's job in the form this collection uses. Exempting the whole site would be gutting the check; exempting a collection that does the same work differently is reading it.
Twelve words is a floor, not a target. It exists to reject "For developers using the API",
which is a category rather than a situation. It cannot tell a concrete paragraph from a long
vague one, and nothing here can. That judgment belongs to fresh-eyes.
A level served only on some pages passes the site-wide check. That used to be the whole answer here. Whether a page served every level it showed was called a job for review, not a job for a counter.
Review missed it. The layout drew the levels on every page. The notes they filter come from worked examples, which only some pages have. That left 56 of the 58 pages carrying the control with nothing for it to act on. Three buttons that dim nothing look just like three that work.
It was a counter's job after all. Both the buttons and the notes are in the built page. The layout now draws a level only where pressing it does something, and the per-page check proves it.
A nav where every level is served can still be inert. Pressing a level dims the notes it does not match, which leaves a page whose notes all name the same audiences with buttons that are each justified and change nothing between them. That is the first fault wearing a smaller number, and the check counts what pressing would do rather than what each level is owed.
A page with no levels at all passes. Most pages explain rather than adapt. A filter over one block of prose is the fault this rubric names, not the cure for it.