Rubric: page purpose

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

You are adding a file and the build has told you it needs a purpose, or you want to know why this repository keeps a map of itself and refuses to let anyone edit it.

Enforced by check_purposes, check_purpose_is_not_published and check_map_is_current.

The claim

Every file says what it is for and how it fits, to whoever maintains it. That sentence never reaches a reader, and the map built from it cannot be out of date.

Observable evidence

• The purpose in each content file's frontmatter, and its length.
• The opening comment of each template, script, stylesheet and data file.
• Whether any purpose text appears in built HTML.
• Whether docs/map.md matches what the build derives from the tree.

The pass bar

Every file has a purpose of at least eight words. No purpose appears in built output. The committed map is byte-identical to a freshly generated one.

Why this rubric exists

Thirty content files, four templates, four stylesheets, four scripts and five data files, and none of them said why it existed. A maintainer arriving cold read a page to work out its job, which is the problem this project exists to solve, one level down and aimed at ourselves.

The sentence is authored and the rest is derived. What a file is for cannot be generated. What links to it, what it links to, and where it is published are things the build already knows, and a map joining the two cannot rot because nobody maintains it.

Ambiguous cases

Why it is not shown to readers. Prose written for two audiences serves the weaker one. The reader's version of this already exists and is the use-cases paragraph, which names situations rather than explaining the file's role in a system the reader does not care about.

Eight words is a floor, not a target. It rejects "the retries page", which is the filename restated. It cannot tell a thoughtful purpose from a lazy one of the right length, and that judgment belongs to fresh-eyes.

A file whose purpose is to be an example. The fixtures under data/examples are exactly that, and the honest purpose is that sentence. Being unremarkable is not the same as being unexplained.

The map is never edited. When it disagrees with the tree, the tree is right and the map was not rebuilt. The check says so rather than reporting a difference and leaving the direction ambiguous.