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.
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 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
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
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
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
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
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
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
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
This repo's
README.mdis 20760 words onnext(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.
README.mdand every other prose document in the repo, such asSPEC.md,DESIGN.mdand prose underdocs/, sentence by sentence, as a newcomer would. Check each sentence against the rules below.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.The rules, sentence by sentence. A sentence fails when a newcomer cannot parse it on first reading. It always fails when it:
Also:
Definition of done.
next.nextfor each rewritten document. The last of them ends its title with (closes #N), N being this issue.agents/pr-reviewer.mdstep 4 to every sentence, before it is squash-merged.make fmtapplied, andscript/cibuildgreen on a fresh clone.Model: opus-5-5
Plan, from a Fable session that wrote none of the documents:
README.md,schema/README.mdandAGENTS.md.REPO_POLICIES.mdandCONVENTIONS.mdare copies of the shared documents insneak/prompts, kept in sync with that source, and stay as they are.nextper rewritten document, each through an independent review that applies the prose rules to every sentence.KICKsection shows only what a client sends, not theKICKevent the server sends (kicker infrom, channel into, kicked nick inparams, reason inbody).#Upperand#upperare two channels); the README says the first and not the second. The005reply still advertisesCASEMAPPING=ascii, by the judgement call on #128.DBURLrow suggestsfile::memory:?cache=sharedfor 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.Model: opus-5-5
Done, in three PRs into
next, each one commit, each gated withscript/cibuildon its head:AGENTS.md: #213schema/README.md: #214README.md: #215 (closes this issue)None of the three passed the rules unchanged; each is rewritten from scratch.
REPO_POLICIES.mdandCONVENTIONS.mdare copies of shared documents kept in sync with their source and are left alone. The JSON files inschema/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.mdasks for one); the web client was checked only for its hashcash andinitChannelStatecalls; the server was not run.Model: fable-5-1
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
Plan for the fresh read, now that #213 and #215 are on
next:README.md,AGENTS.md,schema/README.md.REPO_POLICIES.mdandCONVENTIONS.mdstay out, as decided in #190 (comment).next, gated by an independent review of the changed sentences.Model: opus-5-5
schema/README.mdpasses the fresh read: every sentence meets the rules above and every statement matches the code onnext, checked by reading the HTTP API and IRC listener code, not by running the server. Nothing changed.Model: fable-5-1
AGENTS.mdpasses the fresh read: every sentence parses on first reading and every statement matches the code onnext; nothing changed.Model: fable-5-1