Writers have the context, so they cannot see the places that cannot be read without context. These places are usually first discovered through someone else's review. In this step, that role is done first by a "sub-agent that is not given the context."
The only failures to target are the following six types. All of them arise from a gap between the reader's knowledge and the text, and cannot be caught by checking a sentence on its own.
All examples are aligned to one fictional subject. In a Discord thread saying, "How do you back up your home server? I'm scared that if it disappears I'll be stuck...", the writer writes, "I keep two copies on a NAS and an external disk," and then gets asked, "Where exactly is the storage?" They are writing a reply to that question.
| Type | Name | Example |
|---|---|---|
| 1 | The referent is not determined | The storage is a NAS / the same folder / the remaining three |
| 2 | Renaming and ad hoc coinage | A copy placed outside the server / outside the server |
| 3 | Using borrowed words without defining them | "Measures against getting stuck" (there is no statement of what happening would get you stuck) |
| 4 | Negating something no one said | Not by number of units, but |
| 5 | Restating the previous paragraph in the conclusion paragraph | The entire final paragraph (only one new point) |
| 6 | The scope of the claim drifts | There is no "in my environment," and it reads as a general statement about backups |
Translation-like style, metaphorical verbs, and monotonous sentence endings are looked at in the readability rewriting step, so they are not handled here.
Position
Paragraph structure → sentence norms → readability rewriting → line breaks and blank lines (line-layout) → cold-reader → output. It is placed after readability rewriting because rewriting can change subjects and demonstratives, and types 1 and 6 can newly arise.
Procedure
Paths are relative to the directory containing this SKILL.md.
1. Decide the reader in one line
Write in one line "who will read it" and "what that person already knows." Also write what they do not know.
Example: the person asking. They run a home server and broadly know about NAS, rsync, and external disks. They do not know the writer's hardware setup, scripts, or the backup tools being used. In a thread asking "How do you back up your home server? I'm scared that losing it would leave me stuck...", the writer said "I keep two copies, on a NAS and an external disk," and the person asked, "Where exactly is the storage?"
If there is a question from the other person or a thread title, put it in as-is. For type 3 (borrowed words) and type 4 (a negation no one stated), you cannot judge without knowing what the reader said.
2. Self-check (references/self-check.md）
Apply the six questions yourself and fix what you find. Then run the mechanical check.
python3 scripts/restate_check.py draft.md
LOW A paragraph marked with this is suspected of being type 5.
Name one thing that paragraph says for the first time; if there is none, cut the whole paragraph, and if there is, move that one point into a paragraph that gives a reason.
This check only looks at overlapping words, so it will not catch paraphrased summaries.
In reference documents like READMEs, where the same terms are reused section by section, there are many false positives. There, read the LOW paragraphs and keep them if they contain a new condition, reason, or value.
3. Have a cold reader read it
Launchonesubagent (general-purpose、model: sonnet is enough).
references/reader-prompt.md In the instructions foronly, fill in the one-line reader description from step 1 and the body text and pass it along.
Do not pass along: the conversation history, the source files or paths, the writer's intent, the previous version, or "what was fixed." If you pass along even one of these, the reader will fill in the gaps using the writer's context and miss types 1 through 3.
The reader returns a table of "paragraph # / quote / type / why it is a problem / suggested fix."
4. Handle each point one at a time
For each point, eitherfix itか、write the reason for not fixing it, or do the other. For a reason not to fix it, name specific evidence showing that it is not a problem as is.
- Types 1, 2, 3, 6: write the source of the reader's knowledge, as in "the reader knows ~ (from the ~ statement in the question)."
- Type 4: writewho saidthe claim being negated ("the questioner wrote '~' in the thread"). If you cannot name them, delete the negation.
- Type 5: quote what that paragraph says for the first time.
Do not manufacture evidence after the fact to let a point pass. For example, even if you keep "not by number of units" as a negation that corrects a view the reader might have, if no one actually claimed that, it will just be removed in human review. A reason you cannot name is not a reason.
If the reader's suggested fix contains facts not in the body text, the writer should verify the facts before adding them. Do not put the reader's guesses into the body text as-is.
5. A second pass if needed
The places fixed are 4 or moreor when a paragraph has been cut or moved, run step 3 only once more on the revised version. In this case, launch a new reader (do not reuse the first reader). Handle the points raised in the second round in step 4 and finish. Do not run a third round.
6. Record and show
Along with the body text, attach a short list of the points raised (reasons for fixing / not fixing). This is so that when a person reviews it, they can see what was found by a cold reader and what was not found.
Scripts and tests
scripts/restate_check.py— Mechanical check for type 5. For each paragraph, output the "ratio of words used twice or more in the preceding paragraph (reuse rate of central words)", and for paragraphs at 0.40 or above, attachLOW. The calibration values and known limitations are in the docstring at the top of the file.tests/test_restate_check.py— With a draft on a fictional subject, verify that the final paragraph, which has become a summary, is detected, and that the paragraphs of the final version are not detected.python3 -m unittest discover -s tests
Evaluation
Two drafts each were written with and without this process, and a judge who was not told which condition each was written under counted the failures of the 6 types. The drafts without the process had 4 and 7, and the drafts with it had 1 and 0.