Rewrite README.md and the other prose documents sentence by sentence, on Fable #189

New Issue

2026-10-22T20:16:30+02:00

clawbot commented

2026-10-22 20:16:30 +02:00

This repo's README.md is 5410 words on next (22 October).

sneak, 22 October (chat), after smallwebwaf's README turned out to fail sentence by sentence: "just file issues on the repos about it, and specify that it has to be fable, and make the issues detailed - include your rules. we're not doing this work today (except on smallwebwaf)". What went wrong there, and the rules below, are on sneak/project-management#39 (comment).

Not today. This waits until the fleet restarts (25 October at the earliest) and the repo's manager has room. It is not urgent, but it comes before this repo's next release-candidate tag.

Who. This must be done by Fable: a genius-bar session (--agent genius-bar --model fable --effort xhigh, on a worker account) that wrote none of the documents. Opus workers do not do this unit.

What.

Read README.md and every other prose document in the repo, such as SPEC.md, DESIGN.md and prose under docs/, sentence by sentence, as a newcomer would. Check each sentence against the rules below.
Rewrite each document that fails from scratch. The old text is only the reference for what a reader needs covered; do not edit it in place. Where the old text is unclear or disagrees with the code on next, the code decides what is true and the spec explains the intent. List any disagreement in the PR body; do not settle it silently.
A document that passes is left alone; say so on this issue.
Leave out anything the code does not do, and describe nothing that is not built.

The rules, sentence by sentence. A sentence fails when a newcomer cannot parse it on first reading. It always fails when it:

runs past about 30 words, or chains a list of things with commas where a bulleted list belongs;
stacks clauses so the verb or the subject arrives late, for example "refuses a client a blocklist you name lists";
paraphrases where a plain common name exists, for example "the bans that broken rate limits lead to" instead of rate-limit bans;
narrates the project's own history or plan (milestones, stages, build order, issue links) in a document meant for users;
puts an exception or rare edge case before the main rule, or anywhere in the opening.

Also:

one idea per sentence; subject and verb early;
a false statement fails too, but an inaccurate sentence is fixed by writing a correct short sentence, never by adding qualifiers;
the README leads with what the program is, what it is for and how to use it; every setting goes in a reference section after that; development and testing come last;
plain words, no coined terms, no jargon a newcomer would not know, and any technical word defined on first use;
every identifier, flag, environment variable, path, command and file name in backticks; no markdown tables; no superlatives or praise;
read every sentence once more before committing, and rewrite any you would have to read twice.

Definition of done.

Every prose document in the repo passes the rules above, read sentence by sentence.
Every statement matches the code on next.
One PR into next for each rewritten document. The last of them ends its title with (closes #N), N being this issue.
Each PR passes an independent pr-reviewer applying agents/pr-reviewer.md step 4 to every sentence, before it is squash-merged.
make fmt applied, and script/cibuild green on a fresh clone.

Model: opus-5-5

This repo's `README.md` is 5410 words on `next` (22 October). sneak, 22 October (chat), after smallwebwaf's README turned out to fail sentence by sentence: "just file issues on the repos about it, and specify that it has to be fable, and make the issues detailed - include your rules. we're not doing this work today (except on smallwebwaf)". What went wrong there, and the rules below, are on https://git.eeqj.de/sneak/project-management/issues/39#issuecomment-154280. **Not today.** This waits until the fleet restarts (25 October at the earliest) and the repo's manager has room. It is not urgent, but it comes before this repo's next release-candidate tag. **Who.** This must be done by Fable: a genius-bar session (`--agent genius-bar --model fable --effort xhigh`, on a worker account) that wrote none of the documents. Opus workers do not do this unit. **What.** 1. Read `README.md` and every other prose document in the repo, such as `SPEC.md`, `DESIGN.md` and prose under `docs/`, sentence by sentence, as a newcomer would. Check each sentence against the rules below. 2. Rewrite each document that fails from scratch. The old text is only the reference for what a reader needs covered; do not edit it in place. Where the old text is unclear or disagrees with the code on `next`, the code decides what is true and the spec explains the intent. List any disagreement in the PR body; do not settle it silently. 3. A document that passes is left alone; say so on this issue. 4. Leave out anything the code does not do, and describe nothing that is not built. **The rules, sentence by sentence.** A sentence fails when a newcomer cannot parse it on first reading. It always fails when it: - runs past about 30 words, or chains a list of things with commas where a bulleted list belongs; - stacks clauses so the verb or the subject arrives late, for example "refuses a client a blocklist you name lists"; - paraphrases where a plain common name exists, for example "the bans that broken rate limits lead to" instead of rate-limit bans; - narrates the project's own history or plan (milestones, stages, build order, issue links) in a document meant for users; - puts an exception or rare edge case before the main rule, or anywhere in the opening. Also: - one idea per sentence; subject and verb early; - a false statement fails too, but an inaccurate sentence is fixed by writing a correct short sentence, never by adding qualifiers; - the README leads with what the program is, what it is for and how to use it; every setting goes in a reference section after that; development and testing come last; - plain words, no coined terms, no jargon a newcomer would not know, and any technical word defined on first use; - every identifier, flag, environment variable, path, command and file name in backticks; no markdown tables; no superlatives or praise; - read every sentence once more before committing, and rewrite any you would have to read twice. **Definition of done.** - Every prose document in the repo passes the rules above, read sentence by sentence. - Every statement matches the code on `next`. - One PR into `next` for each rewritten document. The last of them ends its title with (closes #N), N being this issue. - Each PR passes an independent pr-reviewer applying `agents/pr-reviewer.md` step 4 to every sentence, before it is squash-merged. - `make fmt` applied, and `script/cibuild` green on a fresh clone. Model: opus-5-5

clawbot referenced this issue

2026-10-26 01:58:56 +01:00

Checks send no Referer header, so Hetzner answers (closes #191) #192

clawbot commented

2026-10-26 02:12:09 +01:00

Plan. The prose documents here are README.md, TODO.md and test/viewport/README.md. REPO_POLICIES.md is the copy of the sneak/prompts policies that every repo carries, so it is not rewritten here.

After #190 lands (it changes README.md), one genius-bar session on Fable reads the three documents sentence by sentence, against the rules above, and posts here which pass and which fail.
The same session rewrites each failing document from scratch, one PR into next per document. The last PR ends its title with (closes #189).
A fresh Fable session that wrote none of them reviews each PR, reading the whole document as a newcomer and applying step 4 of agents/pr-reviewer.md to every sentence. Its pass is also the reading of the README that comes before the next release-candidate tag.

Model: opus-5-5

Plan. The prose documents here are `README.md`, `TODO.md` and `test/viewport/README.md`. `REPO_POLICIES.md` is the copy of the sneak/prompts policies that every repo carries, so it is not rewritten here. 1. After https://git.eeqj.de/sneak/netwatch/issues/190 lands (it changes `README.md`), one genius-bar session on Fable reads the three documents sentence by sentence, against the rules above, and posts here which pass and which fail. 2. The same session rewrites each failing document from scratch, one PR into `next` per document. The last PR ends its title with `(closes #189)`. 3. A fresh Fable session that wrote none of them reviews each PR, reading the whole document as a newcomer and applying step 4 of `agents/pr-reviewer.md` to every sentence. Its pass is also the reading of the README that comes before the next release-candidate tag. Model: opus-5-5

clawbot commented

2026-10-26 04:18:02 +01:00

Read on next at 8a62f12, sentence by sentence, as a newcomer.

README.md: fails. The opening is one sentence of 47 words. The Entrypoints list has entries of about 80 words with nested exceptions (the script/bootstrap entry). Development and testing come before what the page shows and how to run it. The settings are a table. The Design section uses terms a newcomer cannot parse ("class-based architecture", "DPR-aware scaling"), and the upaas section describes upaas's own behaviour. Example: "script/bootstrap - install all dependencies (the pinned node via nvm unless the node on PATH has the pinned major version and is new enough for the frontend's dependencies, yarn YARN_VERSION via corepack, or npm where there is no corepack, unless the yarn on PATH is exactly that version, ...)".
TODO.md: fails. Workflow, Next Step and Future Steps pass; Status has one 33-word sentence. Most Completed Steps entries run past 30 words a sentence, chain lists with commas and put the verb late. Example (43 words): "Unit tests call cli.Main with no arguments and check that it starts the server, and with each subcommand given no value and two values and with a misspelt subcommand, and check the exit code, the message and that the server does not start".
test/viewport/README.md: fails. It narrates the repo's history (issue numbers, a rejected proposal, "this issue"), puts the reasoning before what the test does, and praises its own design. Examples: "Automated verification of the responsive layout that landed in #5." and "Real limits, so nobody re-parks this issue as needing hardware:".

Three PRs follow, one per document, each on its own branch off next. The README PR closes this issue.

Model: fable-5-1

Read on `next` at `8a62f12`, sentence by sentence, as a newcomer. - `README.md`: fails. The opening is one sentence of 47 words. The Entrypoints list has entries of about 80 words with nested exceptions (the `script/bootstrap` entry). Development and testing come before what the page shows and how to run it. The settings are a table. The Design section uses terms a newcomer cannot parse ("class-based architecture", "DPR-aware scaling"), and the upaas section describes upaas's own behaviour. Example: "`script/bootstrap` - install all dependencies (the pinned node via nvm unless the `node` on `PATH` has the pinned major version and is new enough for the frontend's dependencies, yarn `YARN_VERSION` via corepack, or npm where there is no corepack, unless the `yarn` on `PATH` is exactly that version, ...)". - `TODO.md`: fails. Workflow, Next Step and Future Steps pass; Status has one 33-word sentence. Most Completed Steps entries run past 30 words a sentence, chain lists with commas and put the verb late. Example (43 words): "Unit tests call `cli.Main` with no arguments and check that it starts the server, and with each subcommand given no value and two values and with a misspelt subcommand, and check the exit code, the message and that the server does not start". - `test/viewport/README.md`: fails. It narrates the repo's history (issue numbers, a rejected proposal, "this issue"), puts the reasoning before what the test does, and praises its own design. Examples: "Automated verification of the responsive layout that landed in #5." and "Real limits, so nobody re-parks this issue as needing hardware:". Three PRs follow, one per document, each on its own branch off `next`. The README PR closes this issue. Model: fable-5-1

clawbot referenced a pull request that will close this issue

2026-10-26 04:37:33 +01:00

README.md rewritten sentence by sentence (closes #189) #195

clawbot referenced this issue

2026-10-26 04:40:34 +01:00

TODO.md rewritten sentence by sentence #196

clawbot referenced this issue

2026-10-26 04:40:34 +01:00

test/viewport/README.md rewritten sentence by sentence #197

clawbot referenced this issue from a commit

2026-10-26 04:59:23 +01:00

TODO.md rewritten sentence by sentence