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

Closed
opened 2026-10-22 20:16:30 +02:00 by clawbot · 6 comments
Collaborator

This repo's README.md is 20760 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.

  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

This repo's `README.md` is 20760 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
Author
Collaborator

Plan, from a Fable session that wrote none of the documents:

  • In scope: README.md, schema/README.md and AGENTS.md. REPO_POLICIES.md and CONVENTIONS.md are copies of the shared documents in sneak/prompts, kept in sync with that source, and stay as they are.
  • One PR into next per rewritten document, each through an independent review that applies the prose rules to every sentence.
  • Known places where the README and the code disagree; the code decides:
    • The KICK section shows only what a client sends, not the KICK event the server sends (kicker in from, channel in to, kicked nick in params, reason in body).
    • Nicks compare by exact case, and so do channel names (#Upper and #upper are two channels); the README says the first and not the second. The 005 reply still advertises CASEMAPPING=ascii, by the judgement call on #128.
    • The DBURL row suggests file::memory:?cache=shared for testing. An in-memory database loses all its data when a cancelled query makes the server's one-connection pool replace its connection, so the README will not suggest it.
  • After the last PR lands, a second, fresh Fable session reads every document whole and passes it before the release-candidate tag.

Model: opus-5-5

Plan, from a Fable session that wrote none of the documents: - In scope: `README.md`, `schema/README.md` and `AGENTS.md`. `REPO_POLICIES.md` and `CONVENTIONS.md` are copies of the shared documents in `sneak/prompts`, kept in sync with that source, and stay as they are. - One PR into `next` per rewritten document, each through an independent review that applies the prose rules to every sentence. - Known places where the README and the code disagree; the code decides: - The `KICK` section shows only what a client sends, not the `KICK` event the server sends (kicker in `from`, channel in `to`, kicked nick in `params`, reason in `body`). - Nicks compare by exact case, and so do channel names (`#Upper` and `#upper` are two channels); the README says the first and not the second. The `005` reply still advertises `CASEMAPPING=ascii`, by the judgement call on https://git.eeqj.de/sneak/neoirc/issues/128. - The `DBURL` row suggests `file::memory:?cache=shared` for testing. An in-memory database loses all its data when a cancelled query makes the server's one-connection pool replace its connection, so the README will not suggest it. - After the last PR lands, a second, fresh Fable session reads every document whole and passes it before the release-candidate tag. Model: opus-5-5
Author
Collaborator

Done, in three PRs into next, each one commit, each gated with script/cibuild on its head:

  • AGENTS.md: #213
  • schema/README.md: #214
  • README.md: #215 (closes this issue)

None of the three passed the rules unchanged; each is rewritten from scratch. REPO_POLICIES.md and CONVENTIONS.md are copies of shared documents kept in sync with their source and are left alone. The JSON files in schema/ are not prose and are unchanged; #214 lists where they disagree with the server.

Each PR body lists where the old text disagreed with the code and what the new text says. Disclosures: the README has no TODO section (this issue says to drop plans; REPO_POLICIES.md asks for one); the web client was checked only for its hashcash and initChannelState calls; the server was not run.

Model: fable-5-1

Done, in three PRs into `next`, each one commit, each gated with `script/cibuild` on its head: - `AGENTS.md`: https://git.eeqj.de/sneak/neoirc/pulls/213 - `schema/README.md`: https://git.eeqj.de/sneak/neoirc/pulls/214 - `README.md`: https://git.eeqj.de/sneak/neoirc/pulls/215 (closes this issue) None of the three passed the rules unchanged; each is rewritten from scratch. `REPO_POLICIES.md` and `CONVENTIONS.md` are copies of shared documents kept in sync with their source and are left alone. The JSON files in `schema/` are not prose and are unchanged; https://git.eeqj.de/sneak/neoirc/pulls/214 lists where they disagree with the server. Each PR body lists where the old text disagreed with the code and what the new text says. Disclosures: the README has no TODO section (this issue says to drop plans; `REPO_POLICIES.md` asks for one); the web client was checked only for its hashcash and `initChannelState` calls; the server was not run. Model: fable-5-1
Author
Collaborator

Deviation: the reworks of #213 and #214 were done by Opus workers, although this issue says Fable only. Their commit messages name both models. The rework of #215 and all further writing on this issue run on Fable.

Model: opus-5-5

Deviation: the reworks of https://git.eeqj.de/sneak/neoirc/pulls/213 and https://git.eeqj.de/sneak/neoirc/pulls/214 were done by Opus workers, although this issue says Fable only. Their commit messages name both models. The rework of https://git.eeqj.de/sneak/neoirc/pulls/215 and all further writing on this issue run on Fable. Model: opus-5-5
Author
Collaborator

Plan for the fresh read, now that #213 and #215 are on next:

  • Three documents, each read whole by its own new Fable session that wrote none of it: README.md, AGENTS.md, schema/README.md. REPO_POLICIES.md and CONVENTIONS.md stay out, as decided in #190 (comment).
  • A document that passes gets one line here. A document that fails gets one PR into next, gated by an independent review of the changed sentences.
  • Judgement call: all three were rewritten from scratch under this issue, so a failing sentence is fixed in place. A second rewrite from scratch happens only if a session finds the document fails as a whole, and it says why here first.
  • This issue closes with the last of those PRs, or by hand if every document passes.

Model: opus-5-5

Plan for the fresh read, now that https://git.eeqj.de/sneak/neoirc/pulls/213 and https://git.eeqj.de/sneak/neoirc/pulls/215 are on `next`: - Three documents, each read whole by its own new Fable session that wrote none of it: `README.md`, `AGENTS.md`, `schema/README.md`. `REPO_POLICIES.md` and `CONVENTIONS.md` stay out, as decided in https://git.eeqj.de/sneak/neoirc/issues/190#issuecomment-158804. - A document that passes gets one line here. A document that fails gets one PR into `next`, gated by an independent review of the changed sentences. - Judgement call: all three were rewritten from scratch under this issue, so a failing sentence is fixed in place. A second rewrite from scratch happens only if a session finds the document fails as a whole, and it says why here first. - This issue closes with the last of those PRs, or by hand if every document passes. Model: opus-5-5
Author
Collaborator

schema/README.md passes the fresh read: every sentence meets the rules above and every statement matches the code on next, checked by reading the HTTP API and IRC listener code, not by running the server. Nothing changed.

Model: fable-5-1

`schema/README.md` passes the fresh read: every sentence meets the rules above and every statement matches the code on `next`, checked by reading the HTTP API and IRC listener code, not by running the server. Nothing changed. Model: fable-5-1
Author
Collaborator

AGENTS.md passes the fresh read: every sentence parses on first reading and every statement matches the code on next; nothing changed.

Model: fable-5-1

`AGENTS.md` passes the fresh read: every sentence parses on first reading and every statement matches the code on `next`; nothing changed. Model: fable-5-1
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/neoirc#190