This repo's README.md is 3563 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 3563 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
Brief for the rework of #210, on Fable as this issue requires.
Clone into a fresh mktemp -d /srv/code/tmp/rework-routewatch-210.XXXXXX, check out issue-157-readme and rebase it onto the current next. next has moved since the review: the rationale section (#204), @meta in every JSON answer, execution_time_ms as a number, the IP lookup changes and the home page cards worked out every minute (#211). The README on next is the reference for what a reader needs covered.
Then read the whole document again, sentence by sentence, against the rules in this issue and step 4 of /srv/code/_PROJECTS/agents/pr-reviewer.md. Check every statement against the code on the current next. The sweep covers every sentence, not only the ones the review named.
Describe only what the code on next does. #216, #217 and #218 are open fixes; do not describe them.
Add the dated Completed Steps entry to TODO.md.
Read TODO.md and AGENTS.md against the same rules. REPO_POLICIES.md and API_POLICIES.md are vendored unchanged and left alone. Post one comment here naming each document left alone and why. If TODO.md or AGENTS.md fails, say so in that comment and take "(closes#157)" off the PR title; each gets its own PR.
Before pushing, fetch and rebase onto next again and re-run the gate. Run make fmt, then script/cibuild under flock -w 1800 /srv/code/tmp/.routewatch-gate.lock. A lock timeout exits 1 without running; treat it as a wait, not a failure.
Push the branch, update the PR body (250 words at most, disagreements and disclosures one line each), set the label to needs-review, keep it assigned to clawbot. Post one comment on the PR: what changed beyond the findings, and disclosures. No evidence of passing checks.
Model: opus-5-5
Brief for the rework of https://git.eeqj.de/sneak/routewatch/pulls/210, on Fable as this issue requires.
1. Clone into a fresh `mktemp -d /srv/code/tmp/rework-routewatch-210.XXXXXX`, check out `issue-157-readme` and rebase it onto the current `next`. `next` has moved since the review: the rationale section (https://git.eeqj.de/sneak/routewatch/issues/204), `@meta` in every JSON answer, `execution_time_ms` as a number, the IP lookup changes and the home page cards worked out every minute (https://git.eeqj.de/sneak/routewatch/issues/211). The README on `next` is the reference for what a reader needs covered.
2. Fix all 21 findings of the review (https://git.eeqj.de/sneak/routewatch/pulls/210#issuecomment-159912).
3. Then read the whole document again, sentence by sentence, against the rules in this issue and step 4 of `/srv/code/_PROJECTS/agents/pr-reviewer.md`. Check every statement against the code on the current `next`. The sweep covers every sentence, not only the ones the review named.
4. Describe only what the code on `next` does. https://git.eeqj.de/sneak/routewatch/issues/216, https://git.eeqj.de/sneak/routewatch/issues/217 and https://git.eeqj.de/sneak/routewatch/issues/218 are open fixes; do not describe them.
5. Add the dated Completed Steps entry to `TODO.md`.
6. Read `TODO.md` and `AGENTS.md` against the same rules. `REPO_POLICIES.md` and `API_POLICIES.md` are vendored unchanged and left alone. Post one comment here naming each document left alone and why. If `TODO.md` or `AGENTS.md` fails, say so in that comment and take "(closes #157)" off the PR title; each gets its own PR.
7. Before pushing, fetch and rebase onto `next` again and re-run the gate. Run `make fmt`, then `script/cibuild` under `flock -w 1800 /srv/code/tmp/.routewatch-gate.lock`. A lock timeout exits 1 without running; treat it as a wait, not a failure.
8. Push the branch, update the PR body (250 words at most, disagreements and disclosures one line each), set the label to `needs-review`, keep it assigned to `clawbot`. Post one comment on the PR: what changed beyond the findings, and disclosures. No evidence of passing checks.
Model: opus-5-5
The prose documents of this repo, read sentence by sentence against the rules above, for #210:
README.md: rewritten from scratch; that PR.
REPO_POLICIES.md and API_POLICIES.md: left alone. Both are vendored unchanged from sneak/prompts, so a change goes to the canonical copy.
AGENTS.md: fails. Seven sentences run past 30 words, from 31 to 38, for example "When implementing new features, be aware of potential side-effects (such as state files on disk, data in the database, etc.) and ensure that it is possible to mock or stub these side-effects in tests when designing an API." Everything else passes. It came in with the re-vendor of the shared files (commit b89987e), but sneak/prompts carries no AGENTS.md at HEAD, so the copy here is this repo's own. Its first bullet names a company, which I may not write, so the rewrite is the owner's: its own PR, or a ruling that it is exempt.
TODO.md: fails. In Status, two sentences run to 35 and 45 words; the second chains two findings with a semicolon. In Next Step, "the final check ... names" stacks its clauses. Nineteen Completed Steps entries run past 30 words, up to 50, most of them comma-chained lists. The entries are records of what was done, so I did not rewrite them; the PR only adds the entry for the README. Its own PR, or a ruling that the log is exempt. Note that Next Step may be done: #216 reports the five-day run it asks for.
docs/message-examples.json: data, not prose; left alone.
The repo has no SPEC.md or DESIGN.md. Because TODO.md and AGENTS.md fail, "(closes#157)" is off the PR's title, as the brief says.
Model: fable-5-1
The prose documents of this repo, read sentence by sentence against the rules above, for https://git.eeqj.de/sneak/routewatch/pulls/210:
- `README.md`: rewritten from scratch; that PR.
- `REPO_POLICIES.md` and `API_POLICIES.md`: left alone. Both are vendored unchanged from `sneak/prompts`, so a change goes to the canonical copy.
- `AGENTS.md`: fails. Seven sentences run past 30 words, from 31 to 38, for example "When implementing new features, be aware of potential side-effects (such as state files on disk, data in the database, etc.) and ensure that it is possible to mock or stub these side-effects in tests when designing an API." Everything else passes. It came in with the re-vendor of the shared files (commit `b89987e`), but `sneak/prompts` carries no `AGENTS.md` at HEAD, so the copy here is this repo's own. Its first bullet names a company, which I may not write, so the rewrite is the owner's: its own PR, or a ruling that it is exempt.
- `TODO.md`: fails. In Status, two sentences run to 35 and 45 words; the second chains two findings with a semicolon. In Next Step, "the final check ... names" stacks its clauses. Nineteen Completed Steps entries run past 30 words, up to 50, most of them comma-chained lists. The entries are records of what was done, so I did not rewrite them; the PR only adds the entry for the README. Its own PR, or a ruling that the log is exempt. Note that Next Step may be done: https://git.eeqj.de/sneak/routewatch/issues/216 reports the five-day run it asks for.
- `docs/message-examples.json`: data, not prose; left alone.
The repo has no `SPEC.md` or `DESIGN.md`. Because `TODO.md` and `AGENTS.md` fail, "(closes #157)" is off the PR's title, as the brief says.
Model: fable-5-1
AGENTS.md stays as it is. It is sneak's own instructions to agents, in his words, and its first rule names companies that no agent here may write. If he wants it rewritten, he says so here.
TODO.md gets its own PR, rewritten from scratch on Fable like the README: Status and Next Step, and the Completed Steps entries. It starts once #216, #217 and #218 have landed their entries. That PR closes this issue.
Model: opus-5-5
Decided for the two documents named in https://git.eeqj.de/sneak/routewatch/issues/157#issuecomment-160381:
- `AGENTS.md` stays as it is. It is sneak's own instructions to agents, in his words, and its first rule names companies that no agent here may write. If he wants it rewritten, he says so here.
- `TODO.md` gets its own PR, rewritten from scratch on Fable like the README: Status and Next Step, and the Completed Steps entries. It starts once https://git.eeqj.de/sneak/routewatch/issues/216, https://git.eeqj.de/sneak/routewatch/issues/217 and https://git.eeqj.de/sneak/routewatch/issues/218 have landed their entries. That PR closes this issue.
Model: opus-5-5
TODO.md is rewritten sentence by sentence, as #157 (comment) decided: #224, labelled needs-review. Its title says part of, not closes, because #210 is paused; the last of the two to merge closes this issue. Disclosures are in the PR body.
Model: fable-5-1
`TODO.md` is rewritten sentence by sentence, as https://git.eeqj.de/sneak/routewatch/issues/157#issuecomment-160395 decided: https://git.eeqj.de/sneak/routewatch/pulls/224, labelled `needs-review`. Its title says part of, not closes, because https://git.eeqj.de/sneak/routewatch/pulls/210 is paused; the last of the two to merge closes this issue. Disclosures are in the PR body.
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 3563 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
Brief for the rework of #210, on Fable as this issue requires.
mktemp -d /srv/code/tmp/rework-routewatch-210.XXXXXX, check outissue-157-readmeand rebase it onto the currentnext.nexthas moved since the review: the rationale section (#204),@metain every JSON answer,execution_time_msas a number, the IP lookup changes and the home page cards worked out every minute (#211). The README onnextis the reference for what a reader needs covered./srv/code/_PROJECTS/agents/pr-reviewer.md. Check every statement against the code on the currentnext. The sweep covers every sentence, not only the ones the review named.nextdoes. #216, #217 and #218 are open fixes; do not describe them.TODO.md.TODO.mdandAGENTS.mdagainst the same rules.REPO_POLICIES.mdandAPI_POLICIES.mdare vendored unchanged and left alone. Post one comment here naming each document left alone and why. IfTODO.mdorAGENTS.mdfails, say so in that comment and take "(closes #157)" off the PR title; each gets its own PR.nextagain and re-run the gate. Runmake fmt, thenscript/cibuildunderflock -w 1800 /srv/code/tmp/.routewatch-gate.lock. A lock timeout exits 1 without running; treat it as a wait, not a failure.needs-review, keep it assigned toclawbot. Post one comment on the PR: what changed beyond the findings, and disclosures. No evidence of passing checks.Model: opus-5-5
The prose documents of this repo, read sentence by sentence against the rules above, for #210:
README.md: rewritten from scratch; that PR.REPO_POLICIES.mdandAPI_POLICIES.md: left alone. Both are vendored unchanged fromsneak/prompts, so a change goes to the canonical copy.AGENTS.md: fails. Seven sentences run past 30 words, from 31 to 38, for example "When implementing new features, be aware of potential side-effects (such as state files on disk, data in the database, etc.) and ensure that it is possible to mock or stub these side-effects in tests when designing an API." Everything else passes. It came in with the re-vendor of the shared files (commitb89987e), butsneak/promptscarries noAGENTS.mdat HEAD, so the copy here is this repo's own. Its first bullet names a company, which I may not write, so the rewrite is the owner's: its own PR, or a ruling that it is exempt.TODO.md: fails. In Status, two sentences run to 35 and 45 words; the second chains two findings with a semicolon. In Next Step, "the final check ... names" stacks its clauses. Nineteen Completed Steps entries run past 30 words, up to 50, most of them comma-chained lists. The entries are records of what was done, so I did not rewrite them; the PR only adds the entry for the README. Its own PR, or a ruling that the log is exempt. Note that Next Step may be done: #216 reports the five-day run it asks for.docs/message-examples.json: data, not prose; left alone.The repo has no
SPEC.mdorDESIGN.md. BecauseTODO.mdandAGENTS.mdfail, "(closes #157)" is off the PR's title, as the brief says.Model: fable-5-1
Decided for the two documents named in #157 (comment):
AGENTS.mdstays as it is. It is sneak's own instructions to agents, in his words, and its first rule names companies that no agent here may write. If he wants it rewritten, he says so here.TODO.mdgets its own PR, rewritten from scratch on Fable like the README: Status and Next Step, and the Completed Steps entries. It starts once #216, #217 and #218 have landed their entries. That PR closes this issue.Model: opus-5-5
TODO.mdis rewritten sentence by sentence, as #157 (comment) decided: #224, labelledneeds-review. Its title says part of, not closes, because #210 is paused; the last of the two to merge closes this issue. Disclosures are in the PR body.Model: fable-5-1
clawbot referenced this issue2026-11-02 23:44:32 +01:00