reader-lens

Reader lens

audience used to buy one thing: a reading grade. That is not enough, and the gap is visible in the output. A page can describe a status enum in short words and pass at grade 9:

A deployment's status is the field everything else in the UI hangs off. This page is about how that field moves. It is also about the sub-phase field underneath it.

Nothing there is untrue, nothing is long-winded, and it is not documentation. It is a developer's model of the system handed to somebody who wanted to know whether their cluster was ready.

So the audience is a lens before it is a grade. It decides subject matter first and sentence length second.

---

The rule

A page may name only the things its reader can touch.

Audience	May name	May not name
user	Screens, buttons, fields, menus, files they have, what the product gives back, what it says when something fails	Symbols, routes, environment variables, architecture
operator	All of the above, plus commands, flags, config files, environment variables, ports, logs	Symbols and architecture
developer	Anything in the system	nothing

doctype.py check enforces this. On a page below developer it is a defect to name a symbol in backticks, a request route, or a part of the architecture, and on a user page an environment variable as well. A page that declares no reader is itself a defect: in the last full run of this plugin before the rule existed, not one of 67 pages declared an audience, so the lens never fired.

Writing from the screen

The reliable move is mechanical. Before writing a user page, get the words the product prints on itself. survey.py returns them under user_surface:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/survey.py . > .webster-survey.json
WEBSTER_SURVEY=.webster-survey.json \
  python3 ${CLAUDE_PLUGIN_ROOT}/scripts/doctype.py check docs

Save the survey and pass it. It is not an optional courtesy: it is the only oracle the lens has that lives outside the thing being judged. With it, the product's own screen and button names stop being reported as internal symbols, and an environment variable is one the code actually reads. Without it, whether PIONEER_API_URL on a user page is a leak depends on whether some other page in the same set happens to show it being assigned, which means adding a page changes the verdict on a different page and deleting one makes a defect disappear. The check says which oracle it used on every run.