sneak/webhooker
1
0 Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-10-22 20:16:28 +02:00 by clawbot · 3 comments
clawbot commented 2026-10-22 20:16:28 +02:00
Collaborator
Copy link
Copy source

This repo's README.md is 32273 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 32273 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
sneak commented 2026-10-25 02:57:29 +01:00
Owner
Copy link
Copy source

@clawbot do this now on primary.

@clawbot do this now on primary.
clawbot commented 2026-10-25 03:32:33 +01:00
Author
Collaborator
Copy link
Copy source

Done on primary, per the order above. Three prose documents are in the repo.

  • README.md failed on its first page and throughout (tables, sentences of 50 to 100 words, exceptions before rules, tracker links, test narration). Rewritten from scratch: #561
  • TODO.md failed on several sentences over 30 words and two comma-chained lists. Rewritten from scratch, sections kept: #562 (closes this issue)
  • REPO_POLICIES.md is left alone. It fails the sentence rules too, but it is the fleet-wide policy document vendored into every repo; its front matter says it is kept in sync with its authoritative source. A rewrite here would diverge from every other repo and be overwritten by the next sync. If it is to be rewritten, that belongs at its source (https://git.eeqj.de/sneak/prompts), and is a question for @sneak.

Each PR body lists where the old text disagreed with the code. Both branches have make fmt applied and script/cibuild green. Nothing is merged; the manager starts the reviewers.

Model: fable-5-1

Done on primary, per the order above. Three prose documents are in the repo. - `README.md` failed on its first page and throughout (tables, sentences of 50 to 100 words, exceptions before rules, tracker links, test narration). Rewritten from scratch: https://git.eeqj.de/sneak/webhooker/pulls/561 - `TODO.md` failed on several sentences over 30 words and two comma-chained lists. Rewritten from scratch, sections kept: https://git.eeqj.de/sneak/webhooker/pulls/562 (closes this issue) - `REPO_POLICIES.md` is left alone. It fails the sentence rules too, but it is the fleet-wide policy document vendored into every repo; its front matter says it is kept in sync with its authoritative source. A rewrite here would diverge from every other repo and be overwritten by the next sync. If it is to be rewritten, that belongs at its source (https://git.eeqj.de/sneak/prompts), and is a question for @sneak. Each PR body lists where the old text disagreed with the code. Both branches have `make fmt` applied and `script/cibuild` green. Nothing is merged; the manager starts the reviewers. Model: fable-5-1
clawbot commented 2026-10-26 06:12:09 +01:00
Author
Collaborator
Copy link
Copy source

Documents check before the release-candidate tag (sneak/project-management#39), on README.md at the tip of next.

FAIL, commit e584718eb509aa6dfbefb83153aa739e1f738c4c.

Failing sentences:

  • Lines 201-202: "On a bare host that is loopback, the address only this host can reach." Garden path: "a bare host that is loopback" reads as a clause about the host, and no main verb arrives on first reading. Acceptable: "On a bare host the private address is loopback (127.0.0.1), which only this host can reach." Confidence high.
  • Lines 110-111: "The form also has an HTTP target URL field and an Archive checkbox; each creates that target with the webhook." "That target" names nothing said before; the reader has to work out which target each control creates. Acceptable: "Filling in HTTP target URL creates an http target with the webhook. Ticking Archive creates an archive target." Confidence high.
  • Line 50: "You need the Go version named in go.mod, and Docker for the checks." "The checks" is undefined here (it means make check, first explained under Development); the steps that follow need no Docker, and the Docker run option below names Docker itself. Acceptable: "You need the Go version named in go.mod." Confidence medium.
  • Lines 60-62: "On a host without Docker, make build writes the program to bin/webhooker, and running that file starts webhooker." The opening condition implies the steps above needed Docker; none does, and neither does make build. The Docker option it contrasts with comes only after it. Acceptable: "make build writes the program to bin/webhooker. Running that file starts webhooker." Confidence medium.
  • Line 374: "The password is checked first, and only a failed sign-in is counted." The section opens with a detail of the mechanism: "first" before what, and "counted" toward what, are explained only three sentences later. Acceptable: open with the existing rule sentence, "From the fifth failure within a minute, each failure is answered 429.", and shorten this one to "Only failures are counted." Confidence medium.
  • Lines 437-439: "Each run sends again a retrying delivery the engine is not working on, and a pending one that has sat untouched for 15 minutes." The object "a retrying delivery the engine is not working on" needs a second read, and "sends again" overstates: a retrying delivery is queued for the rest of its wait, not sent at once. Acceptable: "Each run queues again every retrying delivery that no worker holds, and every pending delivery untouched for 15 minutes." Confidence medium.

Not checked: runtime behaviour; nothing was built or run, and the README's claims were read against the code at this commit only. Judgement call: the short, even sentence cadence throughout matches the prose-tells catalogue's "staccato burst", but it is what the gate's own sentence rules produce, so it is not raised.

Model: fable-5-1

Documents check before the release-candidate tag (https://git.eeqj.de/sneak/project-management/issues/39), on `README.md` at the tip of `next`. **FAIL**, commit `e584718eb509aa6dfbefb83153aa739e1f738c4c`. Failing sentences: - **Lines 201-202:** "On a bare host that is loopback, the address only this host can reach." Garden path: "a bare host that is loopback" reads as a clause about the host, and no main verb arrives on first reading. Acceptable: "On a bare host the private address is loopback (`127.0.0.1`), which only this host can reach." Confidence high. - **Lines 110-111:** "The form also has an **HTTP target URL** field and an **Archive** checkbox; each creates that target with the webhook." "That target" names nothing said before; the reader has to work out which target each control creates. Acceptable: "Filling in **HTTP target URL** creates an `http` target with the webhook. Ticking **Archive** creates an archive target." Confidence high. - **Line 50:** "You need the Go version named in `go.mod`, and Docker for the checks." "The checks" is undefined here (it means `make check`, first explained under Development); the steps that follow need no Docker, and the Docker run option below names Docker itself. Acceptable: "You need the Go version named in `go.mod`." Confidence medium. - **Lines 60-62:** "On a host without Docker, `make build` writes the program to `bin/webhooker`, and running that file starts webhooker." The opening condition implies the steps above needed Docker; none does, and neither does `make build`. The Docker option it contrasts with comes only after it. Acceptable: "`make build` writes the program to `bin/webhooker`. Running that file starts webhooker." Confidence medium. - **Line 374:** "The password is checked first, and only a failed sign-in is counted." The section opens with a detail of the mechanism: "first" before what, and "counted" toward what, are explained only three sentences later. Acceptable: open with the existing rule sentence, "From the fifth failure within a minute, each failure is answered `429`.", and shorten this one to "Only failures are counted." Confidence medium. - **Lines 437-439:** "Each run sends again a `retrying` delivery the engine is not working on, and a `pending` one that has sat untouched for 15 minutes." The object "a `retrying` delivery the engine is not working on" needs a second read, and "sends again" overstates: a `retrying` delivery is queued for the rest of its wait, not sent at once. Acceptable: "Each run queues again every `retrying` delivery that no worker holds, and every `pending` delivery untouched for 15 minutes." Confidence medium. Not checked: runtime behaviour; nothing was built or run, and the README's claims were read against the code at this commit only. Judgement call: the short, even sentence cadence throughout matches the prose-tells catalogue's "staccato burst", but it is what the gate's own sentence rules produce, so it is not raised. Model: fable-5-1
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
critical
Extremely important: data loss, a security hole, production down, or basic use impossible
 merge-ready
needs-checks
needs-rebase
needs-review
needs-rework
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/webhooker#558