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)
| Step |
Who |
What |
| 0 Archive |
script |
Copy the original beside the target. Every later check diffs against it. |
| 1 Gate |
script, zero tokens |
scripts/check_plain.py <file> --orig <original> --config <project.json>: frozen blocks unchanged, not longer, no sentence over the cap, banned words, term before definition, number without origin, table spacing. --selftest first. |
| 2 Read |
cheap model |
Dispatch from references/dispatch-templates.md. The reader reads references/defect-catalog.md FIRST, then the page, and reports quote-only findings plus the audit lines. |
| 3 Fix |
cheap model |
Rewrite prose under the frozen contract; frontier writes only the analogy seeds and verifies corrections. |
| 4 Re-gate |
script |
Same command. A fix that fails the gate is not a fix. |
| 5 Append |
orchestrator |
Copy the read's NEW CLASS and RECURRENCE lines into the catalog with the quote. |
| 6 Promote |
orchestrator |
A class seen twice gets a check in the gate, negative-tested (see guarding-silent-failures). |
Model Routing
| Work |
Model |
Why |
| Gates, archives, table normalizing, assembly of frozen blocks |
script |
Zero tokens, never drifts |
| Cold reads with the catalog in hand |
cheap (Sonnet-class) |
Judgment is adequate once the catalog carries the intelligence |
| Prose rewrites under the gate |
cheap |
The gate refuses the countable failures; the charter carries the rest |
| Analogy seeds, catalog entries, verifying a correction, the reader model |
frontier |
Wrong seed or wrong reader model generates a whole class of defects |
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
| Mistake |
Fix |
| Reader re-derives the profile and catalog from scratch each dispatch |
Ten-line dispatch pointing at both files |
| Picture opens the section but the code shows a different bug |
Reader checks the picture against the broken code's actual line |
| Rewriter adds definitions and blows the length cap |
Cut a repeated explanation, never a definition |
| Freezing a heading whose suffix contains a banned word |
Freeze ## N. TITLE; the suffix is prose |
| Gate splitter treats a bullet list or a bold label as one 150-word sentence |
Split on blank lines, bullets, bold labels, semicolons; strip inline code before tags |
| A table followed by prose with no blank line renders an extra row |
Normalizer inserts the blank line |
| Findings answered, catalog never updated |
Step 5 is not optional; the next read pays for it |
| A seed picture handed to a writer as fact |
Seeds are hypotheses; the writer checks the picture against the broken code's changed line (catalog C10); four of sixteen seeds were wrong |
| A scripted fix trusted because it printed "ok" |
Count-assert every replace, exclude frozen regions, make prose regexes wrap-tolerant, re-run the full gate after each script |
| A new gate wired into a pipeline stage that never sees what it checks |
Wire it where the whole artifact exists, then count the cases it must refuse BEFORE trusting the first green build: a done-line gate placed after the builder had peeled the done line off passed ten sheets, eight of which it should have refused |
| A scripted structural edit whose regex treats a markup prefix as text |
Anchor the prefix explicitly (an optional (> ?)? let (.*\S) capture the > itself and three labels lost their blockquote), then grep for the damage signature and render one touched page before the gate's PASS is believed; a blank line inside a paragraph is not a gate class |
| A filler trim that lands inside a frozen block |
Assert the match sits outside code, svg and tables before replacing; the frozen-svg check caught a five-character trim inside a figure caption |
| An exemption marker for a banned form |
Fix the exception to fit the gate instead (characters in a problem became "that player"); a pronoun survived three sweeps, each fixing only the spellings it searched for, and an exemption is where the next survivor hides |
| A wrap-tolerant matcher that stops at a blockquote prefix |
Join words with \s+(?:>\s?)?; a phrase straddling "the\n> interviewer" returned zero matches and looked absent |
| The first sweep of a new check trusted |
Positive-test the guard: 59 of the first 70 hits were the gate's own artifacts (headings read as prose, bold labels split from their definitions, thousands separators, defined numbers re-flagged) |
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.
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.
1---2name: training-the-reader3description: Use when a teaching or study artifact must get plainer across repeated cold reads; when the same reader stalls keep recurring page after page (a term used before it is defined, a number with no origin, a 40-word sentence, a picture that decorates instead of carrying the mechanism); when a rewrite must keep code, figures and tables frozen while only the prose changes; or when cold reads and Feynman-style rewrites are being delegated to cheaper models and each read should start from what the last one found instead of re-deriving it.4---56# Training the Reader78## Overview910The reader's intelligence lives in a file, not in a model. Every cold read starts by reading the11defect catalog, every read ends by appending to it, and any defect class seen twice is promoted12from a judgment the reader must make to a check a script makes for free. Over time the cheap13model spends its tokens only on what scripts cannot judge: does the everyday picture carry the14mechanism, and would a person have to read this twice.1516**REQUIRED BACKGROUND:** superpowers:iterative-lesson-refinement (the reader profile the twin is17derived from) and educational-html-prep (the Feynman page rules). This skill adds the learning18loop those two lack: a catalog that grows, an audit contract that feeds it, a promotion rule.1920## When to Use2122- The maintainer says a page is "word salad", "verbal insanity", "impossible to learn from".23- A cold read returned findings you have seen on an earlier page.24- Many files must be rewritten plainer with the code, figures and numbers untouched.25- The frontier model's quota is the bottleneck and the words will be READ, not spoken.2627Not for: checking truth (use nemesis-review), first-draft authoring, or pages a script can28fully verify.2930## The Loop (one file or one page at a time)3132| Step | Who | What |33|---|---|---|34| 0 Archive | script | Copy the original beside the target. Every later check diffs against it. |35| 1 Gate | script, zero tokens | `scripts/check_plain.py <file> --orig <original> --config <project.json>`: frozen blocks unchanged, not longer, no sentence over the cap, banned words, term before definition, number without origin, table spacing. `--selftest` first. |36| 2 Read | cheap model | Dispatch from `references/dispatch-templates.md`. The reader reads `references/defect-catalog.md` FIRST, then the page, and reports quote-only findings plus the audit lines. |37| 3 Fix | cheap model | Rewrite prose under the frozen contract; frontier writes only the analogy seeds and verifies corrections. |38| 4 Re-gate | script | Same command. A fix that fails the gate is not a fix. |39| 5 Append | orchestrator | Copy the read's NEW CLASS and RECURRENCE lines into the catalog with the quote. |40| 6 Promote | orchestrator | A class seen twice gets a check in the gate, negative-tested (see guarding-silent-failures). |4142## Model Routing4344| Work | Model | Why |45|---|---|---|46| Gates, archives, table normalizing, assembly of frozen blocks | script | Zero tokens, never drifts |47| Cold reads with the catalog in hand | cheap (Sonnet-class) | Judgment is adequate once the catalog carries the intelligence |48| Prose rewrites under the gate | cheap | The gate refuses the countable failures; the charter carries the rest |49| Analogy seeds, catalog entries, verifying a correction, the reader model | frontier | Wrong seed or wrong reader model generates a whole class of defects |5051## Token Rules (each from a real loss)5253- **Write the whole file first, then gate.** A killed agent leaves a finishable file.54- **Assemble by script for anything over ~20 KB.** One 34 KB Write exceeded the output cap.55- **Waves of three or four agents.** A twelve-agent wave died on a five-hour usage limit twice.56- **One read, one write, at most three fix rounds** per file. Never re-read an original.57- **The orchestrator never loads the page.** It reads reports and gate output only.58- **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.59- After a kill, message the SAME agent first; its transcript persists. Re-dispatch only if that fails.6061## The Frozen Contract (the rewrite rule)6263Frozen, asserted by the gate: section headings (the numbered core, not a suffix after a colon),64every code block, every figure, every table value, every measured number. Prose is everything65else, and the rewrite must be SHORTER than the original. A bold "say this out loud" line may be66shortened, never lengthened or removed.6768## Common Mistakes6970| Mistake | Fix |71|---|---|72| Reader re-derives the profile and catalog from scratch each dispatch | Ten-line dispatch pointing at both files |73| Picture opens the section but the code shows a different bug | Reader checks the picture against the broken code's actual line |74| Rewriter adds definitions and blows the length cap | Cut a repeated explanation, never a definition |75| Freezing a heading whose suffix contains a banned word | Freeze `## N. TITLE`; the suffix is prose |76| Gate splitter treats a bullet list or a bold label as one 150-word sentence | Split on blank lines, bullets, bold labels, semicolons; strip inline code before tags |77| A table followed by prose with no blank line renders an extra row | Normalizer inserts the blank line |78| Findings answered, catalog never updated | Step 5 is not optional; the next read pays for it |79| A seed picture handed to a writer as fact | Seeds are hypotheses; the writer checks the picture against the broken code's changed line (catalog C10); four of sixteen seeds were wrong |80| A scripted fix trusted because it printed "ok" | Count-assert every replace, exclude frozen regions, make prose regexes wrap-tolerant, re-run the full gate after each script |81| A new gate wired into a pipeline stage that never sees what it checks | Wire it where the whole artifact exists, then count the cases it must refuse BEFORE trusting the first green build: a done-line gate placed after the builder had peeled the done line off passed ten sheets, eight of which it should have refused |82| A scripted structural edit whose regex treats a markup prefix as text | Anchor the prefix explicitly (an optional `(> ?)?` let `(.*\S)` capture the `>` itself and three labels lost their blockquote), then grep for the damage signature and render one touched page before the gate's PASS is believed; a blank line inside a paragraph is not a gate class |83| A filler trim that lands inside a frozen block | Assert the match sits outside code, svg and tables before replacing; the frozen-svg check caught a five-character trim inside a figure caption |84| An exemption marker for a banned form | Fix the exception to fit the gate instead (characters in a problem became "that player"); a pronoun survived three sweeps, each fixing only the spellings it searched for, and an exemption is where the next survivor hides |85| A wrap-tolerant matcher that stops at a blockquote prefix | Join words with `\s+(?:>\s?)?`; a phrase straddling "the\n> interviewer" returned zero matches and looked absent |86| The first sweep of a new check trusted | Positive-test the guard: 59 of the first 70 hits were the gate's own artifacts (headings read as prose, bold labels split from their definitions, thousands separators, defined numbers re-flagged) |8788## When to Stop8990The teaching score plateaus early (7 to 8); the finish score is what the loop moves, and it moves on91executability: setup printed before launch, the condition on the bullet it modifies, the folder92located on the first command line, a count stated where a chip is charged. When a re-read returns93"none, ship it" and its siblings return one or two judgment items, the reader-twin is exhausted.94Stop dispatching; the next signal is the human's own stalls, which no twin can predict.9596## Provenance9798- 2026-09-02, born: a 21-walkthrough interview-prep library the maintainer called "verbal insanity" after a99 rebuild had reused it verbatim. Baseline cold reads 7 teach / 5 finish. After the loop: 21/21 files pass100 the gate, ten day pages cold-read by catalog-armed cheap readers (teach 7 to 8, finish 6 to 7; one page101 re-read after fixes moved 5 to 7), a 220k-token picture sweep found eight defects four full reads had102 missed, and eight judgment classes became script checks the same day. Catalog at 37 classes.103- 2026-09-02, the guard guarded its author: four of the orchestrator's own scripted fixes broke files in104 ways that looked finished (a regex ate two time lines, a trim edited a frozen table row, a normalizer105 overran a length ceiling by one character, an example id in a command line inflated every plan chip).106 Every one was caught by a check written hours earlier for a different reason.107- 2026-09-02, second pass: nine pages re-read after fixes by catalog-armed cheap readers on plain-text renders108 (80k-106k tokens per read, about half the HTML cost), each told the previous reads' findings and made to quote109 where each fix landed before scoring. Finish scores reached 7 or 8 on all ten pages (two needed a third read).110 Five new classes (C38-C42); five judgment classes became builder rules the same day (a conditional done line,111 no typed totals, no pronouns, a legend derived from the chips, hub chips synced from the pages). Three of the112 orchestrator's own scripted fixes misfired and were caught by gates or renders, never by their own success113 messages.
srfinch17