Rubric: reader orientation

Written by a person. Last read by a person on 2026-09-05, 3 days ago. Its facts were checked by the eval suite on 2026-09-07.

Enforced by check_use_cases and check_levels_served.

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.

Observable evidence

• The use_cases value 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 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.

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 check is site-wide because the levels are declared site-wide. Whether a particular page serves every level it displays is a question for review, not for a counter.