Training the Reader

Overview

The reader's intelligence lives in a file, not in a model. Every cold read starts by reading the defect catalog, every read ends by appending to it, and any defect class seen twice is promoted from a judgment the reader must make to a check a script makes for free. Over time the cheap model spends its tokens only on what scripts cannot judge: does the everyday picture carry the mechanism, and would a person have to read this twice.

REQUIRED BACKGROUND: superpowers:iterative-lesson-refinement (the reader profile the twin is derived from) and educational-html-prep (the Feynman page rules). This skill adds the learning loop those two lack: a catalog that grows, an audit contract that feeds it, a promotion rule.

When to Use

• The maintainer says a page is "word salad", "verbal insanity", "impossible to learn from".
• A cold read returned findings you have seen on an earlier page.
• Many files must be rewritten plainer with the code, figures and numbers untouched.
• The frontier model's quota is the bottleneck and the words will be READ, not spoken.

Not for: checking truth (use nemesis-review), first-draft authoring, or pages a script can fully verify.

The Loop (one file or one page at a time)

Model Routing

Token Rules (each from a real loss)

• Write the whole file first, then gate. A killed agent leaves a finishable file.
• Assemble by script for anything over ~20 KB. One 34 KB Write exceeded the output cap.
• Waves of three or four agents. A twelve-agent wave died on a five-hour usage limit twice.
• One read, one write, at most three fix rounds per file. Never re-read an original.
• The orchestrator never loads the page. It reads reports and gate output only.
• Readers read a RENDER, never the HTML. scripts/render_page.py <page.html> <out.txt> keeps headings, lists, fenced code, figure step captions and [DETAILS] markers; reads cost about half (78k-106k against 156k-208k) with no loss the reports could show.
• After a kill, message the SAME agent first; its transcript persists. Re-dispatch only if that fails.

The Frozen Contract (the rewrite rule)

Frozen, asserted by the gate: section headings (the numbered core, not a suffix after a colon), every code block, every figure, every table value, every measured number. Prose is everything else, and the rewrite must be SHORTER than the original. A bold "say this out loud" line may be shortened, never lengthened or removed.

Common Mistakes

When to Stop

The teaching score plateaus early (7 to 8); the finish score is what the loop moves, and it moves on executability: setup printed before launch, the condition on the bullet it modifies, the folder located on the first command line, a count stated where a chip is charged. When a re-read returns "none, ship it" and its siblings return one or two judgment items, the reader-twin is exhausted. Stop dispatching; the next signal is the human's own stalls, which no twin can predict.

Field addition (2026-09-30): HTML pages, dropped hedges, and what a twin cannot know

A ten-page HTML teaching site for a codebase ran through this loop: 409 sentences over 30 words went to 0, teach 7 to 8, finish 6 to 7. What it added:

• HTML works through the render. Gate the text render (render_page.py), normalize its numbered headings to the gate's form, drop the one-line figure summaries, and freeze every <svg> byte for byte against the archived HTML. A wrapper of about 100 lines did it; the gate itself was unchanged.
• A project config REPLACES list keys. Build it in code from the defaults plus the project's extras. In a codebase KB, a file:line citation is a number's origin; without that cue every line number read as unsourced.
• The gate passed while the rewrite changed 10 claims. Seven were dropped hedges. Per this skill's own promotion rule the class became a check: each hedge term's count in the rewrite must not fall below the original, with an explicit flag to pass after a writer checks that the hedge moved rather than vanished. The other three needed a drift auditor reading the before and after renders. Run one after every site-wide prose pass.
• Gate quirks shape the prose. The sentence splitter did not split before a sentence opening with inline code, so writers started sentences with filler to satisfy it and prefixed source citations with "Code:". Harmless, but it is the gate writing the page; when a quirk is worked around twice, fix the splitter.
• A twin knows how the reader reads, not what the reader must do. The final read's top fix was "add a day-one block: what to ask first". Built without asking, it was wrong: the reader already had assigned work. Act on a twin's findings about the text; turn its claims about the reader's needs into one question to the human.

Provenance

• 2026-09-02, born: a 21-walkthrough interview-prep library the maintainer called "verbal insanity" after a rebuild had reused it verbatim. Baseline cold reads 7 teach / 5 finish. After the loop: 21/21 files pass the gate, ten day pages cold-read by catalog-armed cheap readers (teach 7 to 8, finish 6 to 7; one page re-read after fixes moved 5 to 7), a 220k-token picture sweep found eight defects four full reads had missed, and eight judgment classes became script checks the same day. Catalog at 37 classes.
• 2026-09-02, the guard guarded its author: four of the orchestrator's own scripted fixes broke files in ways that looked finished (a regex ate two time lines, a trim edited a frozen table row, a normalizer overran a length ceiling by one character, an example id in a command line inflated every plan chip). Every one was caught by a check written hours earlier for a different reason.
• 2026-09-02, second pass: nine pages re-read after fixes by catalog-armed cheap readers on plain-text renders (80k-106k tokens per read, about half the HTML cost), each told the previous reads' findings and made to quote where each fix landed before scoring. Finish scores reached 7 or 8 on all ten pages (two needed a third read). Five new classes (C38-C42); five judgment classes became builder rules the same day (a conditional done line, no typed totals, no pronouns, a legend derived from the chips, hub chips synced from the pages). Three of the orchestrator's own scripted fixes misfired and were caught by gates or renders, never by their own success messages.

Field addition (2026-11-02): the lean form for a one-page dashboard, and a second reader on a cheaper model

A project dashboard (one HTML page, about 100 KB, a flow diagram and ring meters) got the loop without the gate or the archive: render with scripts/render_page.py, ONE Sonnet read armed with references/defect-catalog.md (108K; TEACH 4, FINISH 6), the fixes made in the page builder, then a Haiku read of the first 180 lines of the new render as a named persona (a C#/SQL expert new to ML, 92K; TEACH 5, FINISH 7, every ask "clear"). What the reads found that the author and a visual screen could not: a glossary folded at the bottom and stale from a month before (three methods and a test set the page no longer had), one identical outcome string printed 37 times, "notes 12" as a link label, "you" meaning two different people on one page, glued fragments where ; had become . without a capital, and no sentence saying what is live for users (nothing was). Two of those became builder rules the same evening (capitalise after the inserted full stop, the shared outcome said once in the summary). Rules that held: the word list sits beside the first use, not at the bottom; a dashboard says what is NOT in production; the second read goes to the cheaper model and gets a persona and a line limit, and its "clear / unclear" per ask is the finish score that matters.