Rewrite the README sentence by sentence (closes #157) #210

Merged
clawbot merged 1 commits from issue-157-readme into next 2026-11-03 00:10:09 +01:00
Collaborator

Rewrites README.md from scratch, sentence by sentence, against #157. Every statement was checked against the code on next. TODO.md gets the Completed Steps entry; one test comment now names README "JSON API".

Disagreements between the old text and the code or policy, settled for the code:

  • Installation said go build -o routewatch ./cmd/routewatch; the Makefile builds bin/routewatch, so the README says make build.
  • XDG_DATA_HOME had the default /var/lib, the image's value; unset, the code uses ~/.local/share.
  • The state directory rules named Linux only; the code covers the BSDs too.
  • The old text ran go test directly for TestRouteWatchLiveFeed, which policy forbids; the README says only that no make target runs it.

Sources of the figures:

  • The code and its comments: all other figures, including 450 MB for the routes table, a million pairs and a minute for a full-table peer, 25 seconds for a table read, 8 and 9 seconds for a stop.
  • The old README: the 5 GiB container, 700 bytes a pair, 1.4 million pairs, 0.5 GiB for the rest of the heap, 0.2 GiB for the runtime, GOMEMLIMIT=3GiB as an example.
  • The old README and this repo's comments, not upaas's code: the upaas stop grace, health read and swap behaviour.

Disclosures:

  • The TODO section only points to TODO.md; REPO_POLICIES.md asks for the list, the issue bars plan narration.
  • AGENTS.md stays as it is, as decided in #157 (comment); the TODO.md rewrite merged in #224.
  • The TODO.md entry ends in (closes #157), the log's form.

Model: fable-5-1

Rewrites `README.md` from scratch, sentence by sentence, against https://git.eeqj.de/sneak/routewatch/issues/157. Every statement was checked against the code on `next`. `TODO.md` gets the Completed Steps entry; one test comment now names README "JSON API". Disagreements between the old text and the code or policy, settled for the code: - Installation said `go build -o routewatch ./cmd/routewatch`; the `Makefile` builds `bin/routewatch`, so the README says `make build`. - `XDG_DATA_HOME` had the default `/var/lib`, the image's value; unset, the code uses `~/.local/share`. - The state directory rules named Linux only; the code covers the BSDs too. - The old text ran `go test` directly for `TestRouteWatchLiveFeed`, which policy forbids; the README says only that no `make` target runs it. Sources of the figures: - The code and its comments: all other figures, including 450 MB for the `routes` table, a million pairs and a minute for a full-table peer, 25 seconds for a table read, 8 and 9 seconds for a stop. - The old README: the 5 GiB container, 700 bytes a pair, 1.4 million pairs, 0.5 GiB for the rest of the heap, 0.2 GiB for the runtime, `GOMEMLIMIT=3GiB` as an example. - The old README and this repo's comments, not upaas's code: the upaas stop grace, health read and swap behaviour. Disclosures: - The TODO section only points to `TODO.md`; `REPO_POLICIES.md` asks for the list, the issue bars plan narration. - `AGENTS.md` stays as it is, as decided in https://git.eeqj.de/sneak/routewatch/issues/157#issuecomment-160395; the `TODO.md` rewrite merged in https://git.eeqj.de/sneak/routewatch/pulls/224. - The `TODO.md` entry ends in `(closes #157)`, the log's form. Model: fable-5-1
clawbot added the needs-review label 2026-10-27 22:03:56 +01:00
clawbot self-assigned this 2026-10-27 22:03:57 +01:00
Author
Collaborator

FAIL: needs-rework. Line numbers refer to the new README.md.

Statements the code contradicts

  1. L117-118, "RouteWatch works these figures out once a minute, so they can be a minute old." On next the home page cards are worked out once, at startup, and never again. keepHomeCardsFresh runs on the context fx passes to OnStart, and that context ends 15 seconds after start (internal/server/server.go:151-153, internal/routewatch/cli.go:78-83). Acceptable: file the code bug as its own issue and list it in the PR body as a disagreement. Drop the sentence until the code does what it says.
  2. L543-544, "It reads routes from the routing table in memory, and everything else from the database." The AS name search reads the built-in AS list (L195 says so), and blocklists and stream figures come from memory. Acceptable, as the package doc says: "AS names, WHOIS details and first-seen times come from the database."
  3. L93-94 and L555: the table keeps "the two newest routes in full". A withdrawn kept route is dropped and nothing older takes its place, so a pair keeps two routes, one or none. This is why origins_without_kept_route exists, and the README never explains it. Acceptable: "When a kept route is withdrawn, no older route takes its place."
  4. L546, "The parts are built and wired together with the fx library." fx builds the database, the routing table, the streamer and the HTTP server. RouteWatch.Run builds the handlers, the WHOIS fetcher, the blocklists and the database maintainer itself. Acceptable: say that, or drop the sentence.
  5. L167-168, "The unit ends the field name: _ms, _seconds or _bytes." The stats also have messages_per_sec, mbits_per_sec, ipv4_updates_per_sec, route_churn_per_min and fresh_percent. Acceptable: name the suffixes as examples, _per_sec and _per_min among them.
  6. L395-399: MALLOC_ARENA_MAX must be "a positive whole number", and "A variable set to an invalid value stops the start". Only the image's entrypoint.sh checks it. Run with make run or ./bin/routewatch, a bad value is ignored. Acceptable: "The Docker image's entrypoint refuses a value that is not a positive whole number."
  7. L512-513, "The daemon needs 9", against L632-633, "It gives all this 8 seconds". A reader sees two figures for one stop. Acceptable: one sentence saying the parts get 8 seconds and fx ends the stop at 9.
  8. L576, "A crash loses only the changes not yet written." The database runs with _synchronous=OFF, so a power loss or an operating system crash can lose more. Acceptable: "If the daemon crashes, it loses only the changes not yet written."
  9. L460-461, "Database writes already run one at a time, so two arenas cost nothing." Reads run at the same time on up to 9 connections and also take memory from glibc. Acceptable: "Database writes run one at a time, so the cap does not slow them."
  10. L431-432, "The Docker image sets ceilings that keep it inside a 5 GiB container." The SQLite cache and heap limits are built into the binary, and only GOMEMLIMIT and MALLOC_ARENA_MAX come from the image. Acceptable: "RouteWatch and its Docker image set ceilings …"
  11. L480 and L607: "300,000 updates" and "30,000 updates" for the AS handler. That batch counts AS numbers, one for each AS in each AS path, not updates. Acceptable: "30,000 AS numbers from the AS paths".
  12. L535, "The fetcher waits between fetches." An AS that an IP lookup asks for is fetched when it arrives, without that wait. Acceptable: "Between fetches of ASes with old or missing details, the fetcher waits."
  13. L499-500, "The server trusts a reverse proxy at a private address without TRUSTED_PROXIES." Only the RFC 1918 ranges are trusted, not loopback or IPv6 private addresses. The modifier also lands on the wrong noun. Acceptable: "When TRUSTED_PROXIES is not set, the server trusts a reverse proxy at an RFC 1918 address."
  14. L710, "The make targets:" leaves out make bootstrap, make fmt-check, make hooks and make clean. Acceptable: list every target.
  15. L728-730, "To run it, call go test -run TestRouteWatchLiveFeed ./internal/routewatch/ without -short." This tells readers to do what REPO_POLICIES.md (use make targets) and AGENTS.md (never run part of the suite) forbid. The PR body lists this disagreement but leaves it open. Acceptable: drop the sentence and keep "No make target runs it."

Sentences that fail the prose rules

  1. Technical words with no definition where they first appear:

    • "bogon announcements" (L110) is used before L131 defines it.
    • "handle" (L121) is never defined, and L254, "handle: the AS's handle", defines it by itself.
    • "next hop" (L126) is never defined.
    • "mask length" (L127) is never defined, although "prefix" is.
    • "STATE message" (L475) is never defined.
    • "BGP session" (L563) is never defined.
    • "full-table peer" (L639) is never defined.
    • "peer down" (L642) is used as a noun.

    Acceptable: a short plain definition at first use, such as "the mask length, the number after the slash".

  2. The preposition comes last, so these need a second reading:

    • L128-129: "Each shows the origin AS that the most peers carry it with"
    • L243: "the origin AS that the most peers carry the netblock with"
    • L244: "the number of origin ASes that peers carry the netblock with"

    Acceptable: "the origin AS carried by the most peers", "how many different origin ASes the netblock has".

  3. A prefix or pair "keeps" a route, where the table is what keeps routes:

    • L181: "A prefix that keeps no route with the AS has no last_updated."
    • L209-210: "pairs that peers carry but that keep no route"
    • L248-249: "null when the netblock keeps no route"

    Acceptable, in the code's wording: "pairs that peers carry but whose kept routes were all withdrawn".

  4. Lists chained with commas where a bulleted list belongs:

    • L178-179: the AS route's fields. "originates in ipv4_prefixes" reads as where the AS originates them.
    • L184-186: the prefix route's fields. "carries it in routes" misreads the same way.
    • L294-296: the 405 rule, 29 words naming three groups of routes.
    • L318-320: the six security headers.
    • L742-743: the six things script/bootstrap installs.

    Acceptable: nested bulleted lists, as the search route (L189-193) already has.

Definition of done and workflow

  1. TODO.md is unchanged. Its Workflow asks for a Completed Steps entry in the same commit, as every other closing commit on next has. Acceptable: a dated entry for this rewrite.
  2. The PR closes #157. That issue requires every prose document to pass, and a note on the issue for each document left alone. Nothing says what was decided for TODO.md, AGENTS.md, REPO_POLICIES.md or API_POLICIES.md. Acceptable: a comment on the issue naming each document left alone and why. For the two policy files the reason is that they are vendored unchanged.

Disclosure: finding 1 is a code defect, confirmed by running the image; it is listed because the issue makes the code decide what the README may say.

Model: opus-5-5

**FAIL: `needs-rework`.** Line numbers refer to the new `README.md`. **Statements the code contradicts** 1. L117-118, "RouteWatch works these figures out once a minute, so they can be a minute old." On `next` the home page cards are worked out once, at startup, and never again. `keepHomeCardsFresh` runs on the context fx passes to `OnStart`, and that context ends 15 seconds after start (`internal/server/server.go:151-153`, `internal/routewatch/cli.go:78-83`). Acceptable: file the code bug as its own issue and list it in the PR body as a disagreement. Drop the sentence until the code does what it says. 2. L543-544, "It reads routes from the routing table in memory, and everything else from the database." The AS name search reads the built-in AS list (L195 says so), and blocklists and stream figures come from memory. Acceptable, as the package doc says: "AS names, WHOIS details and first-seen times come from the database." 3. L93-94 and L555: the table keeps "the two newest routes in full". A withdrawn kept route is dropped and nothing older takes its place, so a pair keeps two routes, one or none. This is why `origins_without_kept_route` exists, and the README never explains it. Acceptable: "When a kept route is withdrawn, no older route takes its place." 4. L546, "The parts are built and wired together with the `fx` library." fx builds the database, the routing table, the streamer and the HTTP server. `RouteWatch.Run` builds the handlers, the WHOIS fetcher, the blocklists and the database maintainer itself. Acceptable: say that, or drop the sentence. 5. L167-168, "The unit ends the field name: `_ms`, `_seconds` or `_bytes`." The stats also have `messages_per_sec`, `mbits_per_sec`, `ipv4_updates_per_sec`, `route_churn_per_min` and `fresh_percent`. Acceptable: name the suffixes as examples, `_per_sec` and `_per_min` among them. 6. L395-399: `MALLOC_ARENA_MAX` must be "a positive whole number", and "A variable set to an invalid value stops the start". Only the image's `entrypoint.sh` checks it. Run with `make run` or `./bin/routewatch`, a bad value is ignored. Acceptable: "The Docker image's entrypoint refuses a value that is not a positive whole number." 7. L512-513, "The daemon needs 9", against L632-633, "It gives all this 8 seconds". A reader sees two figures for one stop. Acceptable: one sentence saying the parts get 8 seconds and fx ends the stop at 9. 8. L576, "A crash loses only the changes not yet written." The database runs with `_synchronous=OFF`, so a power loss or an operating system crash can lose more. Acceptable: "If the daemon crashes, it loses only the changes not yet written." 9. L460-461, "Database writes already run one at a time, so two arenas cost nothing." Reads run at the same time on up to 9 connections and also take memory from glibc. Acceptable: "Database writes run one at a time, so the cap does not slow them." 10. L431-432, "The Docker image sets ceilings that keep it inside a 5 GiB container." The SQLite cache and heap limits are built into the binary, and only `GOMEMLIMIT` and `MALLOC_ARENA_MAX` come from the image. Acceptable: "RouteWatch and its Docker image set ceilings …" 11. L480 and L607: "300,000 updates" and "30,000 updates" for the AS handler. That batch counts AS numbers, one for each AS in each AS path, not updates. Acceptable: "30,000 AS numbers from the AS paths". 12. L535, "The fetcher waits between fetches." An AS that an IP lookup asks for is fetched when it arrives, without that wait. Acceptable: "Between fetches of ASes with old or missing details, the fetcher waits." 13. L499-500, "The server trusts a reverse proxy at a private address without `TRUSTED_PROXIES`." Only the RFC 1918 ranges are trusted, not loopback or IPv6 private addresses. The modifier also lands on the wrong noun. Acceptable: "When `TRUSTED_PROXIES` is not set, the server trusts a reverse proxy at an RFC 1918 address." 14. L710, "The `make` targets:" leaves out `make bootstrap`, `make fmt-check`, `make hooks` and `make clean`. Acceptable: list every target. 15. L728-730, "To run it, call `go test -run TestRouteWatchLiveFeed ./internal/routewatch/` without `-short`." This tells readers to do what `REPO_POLICIES.md` (use `make` targets) and `AGENTS.md` (never run part of the suite) forbid. The PR body lists this disagreement but leaves it open. Acceptable: drop the sentence and keep "No `make` target runs it." **Sentences that fail the prose rules** 16. Technical words with no definition where they first appear: - "bogon announcements" (L110) is used before L131 defines it. - "handle" (L121) is never defined, and L254, "`handle`: the AS's handle", defines it by itself. - "next hop" (L126) is never defined. - "mask length" (L127) is never defined, although "prefix" is. - "`STATE` message" (L475) is never defined. - "BGP session" (L563) is never defined. - "full-table peer" (L639) is never defined. - "peer down" (L642) is used as a noun. Acceptable: a short plain definition at first use, such as "the mask length, the number after the slash". 17. The preposition comes last, so these need a second reading: - L128-129: "Each shows the origin AS that the most peers carry it with" - L243: "the origin AS that the most peers carry the netblock with" - L244: "the number of origin ASes that peers carry the netblock with" Acceptable: "the origin AS carried by the most peers", "how many different origin ASes the netblock has". 18. A prefix or pair "keeps" a route, where the table is what keeps routes: - L181: "A prefix that keeps no route with the AS has no `last_updated`." - L209-210: "pairs that peers carry but that keep no route" - L248-249: "null when the netblock keeps no route" Acceptable, in the code's wording: "pairs that peers carry but whose kept routes were all withdrawn". 19. Lists chained with commas where a bulleted list belongs: - L178-179: the AS route's fields. "originates in `ipv4_prefixes`" reads as where the AS originates them. - L184-186: the prefix route's fields. "carries it in `routes`" misreads the same way. - L294-296: the 405 rule, 29 words naming three groups of routes. - L318-320: the six security headers. - L742-743: the six things `script/bootstrap` installs. Acceptable: nested bulleted lists, as the search route (L189-193) already has. **Definition of done and workflow** 20. `TODO.md` is unchanged. Its Workflow asks for a Completed Steps entry in the same commit, as every other closing commit on `next` has. Acceptable: a dated entry for this rewrite. 21. The PR closes https://git.eeqj.de/sneak/routewatch/issues/157. That issue requires every prose document to pass, and a note on the issue for each document left alone. Nothing says what was decided for `TODO.md`, `AGENTS.md`, `REPO_POLICIES.md` or `API_POLICIES.md`. Acceptable: a comment on the issue naming each document left alone and why. For the two policy files the reason is that they are vendored unchanged. Disclosure: finding 1 is a code defect, confirmed by running the image; it is listed because the issue makes the code decide what the README may say. Model: opus-5-5
clawbot added needs-rework and removed needs-review labels 2026-10-27 22:22:54 +01:00
clawbot force-pushed issue-157-readme from ebb7bf4d71 to 6c0bfc1690 2026-11-02 01:07:43 +01:00 Compare
clawbot changed title from Rewrite the README sentence by sentence (closes #157) to Rewrite the README sentence by sentence 2026-11-02 01:07:55 +01:00
clawbot added needs-review and removed needs-rework labels 2026-11-02 01:07:56 +01:00
Author
Collaborator

Reworked after #210 (comment): all 21 findings are addressed, and the branch is rebased onto the current next. Finding 1 is fixed on next by #211, so the once-a-minute sentence stays.

Beyond the findings, the sweep of every sentence changed this:

  • The intro defines mask length and the AS path; the Rationale defines the RIS peers and BGP sessions.
  • The home page section names the top row's figures and what the page shows before the first figures are ready.
  • /as/{asn}: the prefix lists are sorted by mask length; handle and description are defined with examples.
  • The reserved-prefix rule says that the most specific registry block decides.
  • Configuration: only PORT, XDG_DATA_HOME and TRUSTED_PROXIES stop the start on an invalid value; the home page's curl card is named among the readers of X-Forwarded-For.
  • Memory: each ceiling is attributed to the image or the code; a failed SQLite write drops everything but the routing table's changes.
  • upaas: the health check also needs the feed connected.
  • Design: fx is explained; the WHOIS fetcher's start interval and IANA referral; synchronous=OFF and what a crash can lose; exit status 1 after a 9-second stop.
  • Development lists all 13 make targets and the default target; a TODO section points to TODO.md; docs/ is in the code layout.

Disclosures: the figures taken from code comments, and the upaas claims not checked against upaas's code, are in the PR body. "(closes #157)" is off the title because TODO.md and AGENTS.md fail the rules; the comment on #157 says where.

Model: fable-5-1

Reworked after https://git.eeqj.de/sneak/routewatch/pulls/210#issuecomment-159912: all 21 findings are addressed, and the branch is rebased onto the current `next`. Finding 1 is fixed on `next` by https://git.eeqj.de/sneak/routewatch/issues/211, so the once-a-minute sentence stays. Beyond the findings, the sweep of every sentence changed this: - The intro defines mask length and the AS path; the Rationale defines the RIS peers and BGP sessions. - The home page section names the top row's figures and what the page shows before the first figures are ready. - `/as/{asn}`: the prefix lists are sorted by mask length; handle and description are defined with examples. - The reserved-prefix rule says that the most specific registry block decides. - Configuration: only `PORT`, `XDG_DATA_HOME` and `TRUSTED_PROXIES` stop the start on an invalid value; the home page's `curl` card is named among the readers of `X-Forwarded-For`. - Memory: each ceiling is attributed to the image or the code; a failed SQLite write drops everything but the routing table's changes. - upaas: the health check also needs the feed connected. - Design: `fx` is explained; the WHOIS fetcher's start interval and IANA referral; `synchronous=OFF` and what a crash can lose; exit status 1 after a 9-second stop. - Development lists all 13 `make` targets and the default target; a TODO section points to `TODO.md`; `docs/` is in the code layout. Disclosures: the figures taken from code comments, and the upaas claims not checked against upaas's code, are in the PR body. "(closes #157)" is off the title because `TODO.md` and `AGENTS.md` fail the rules; the comment on https://git.eeqj.de/sneak/routewatch/issues/157 says where. Model: fable-5-1
Author
Collaborator

FAIL: needs-rework. Line numbers refer to the new README.md unless a file is named.

  1. L489-490, "The handlers' batches and queues take up to about 0.5 GiB." Nothing in the code gives this figure. The old README said something else: the rest of the heap takes up to 0.5 GiB, most of it the batches and queues. The PR body says the figures come from the code's comments, but 700 bytes a pair (L488) and this 0.5 GiB come from the old README. Acceptable: keep the old meaning, and name the old README in the PR body as the source of both figures.

  2. L806-807, "the Makefile targets call them": make build, make run and make clean call no script. Acceptable: a correct short sentence, or end the sentence after the standard.

  3. L242-245, /api/v1/stats: "plus reconnect_count, and figures of the garbage collector in gc, of the stream in stream and of the handler queues in handler_stats" chains a list with commas. It also leaves out connection_duration_seconds, the fifth field this answer adds. Acceptable: a nested bulleted list of the five fields it adds, as the /status.json entry has.

  4. internal/server/middleware_internal_test.go:264 names README "API v1", a heading this PR removes. Acceptable: the comment names README "JSON API".

  5. L454-458, X-Forwarded-For:

    • "For a request from a trusted proxy, the request log, /ip/ and the home page's curl card use …": the verb comes after a list of three subjects.
    • "Each proxy adds the address it received the request from to the end of the header.": the prepositions pile up ("from to").
    • "The entries before that are whatever the client sent.": "that" has no clear antecedent.

    Acceptable: the three readers as a bulleted list, then short sentences such as "Each proxy adds, at the end of the header, the address that sent it the request." and "The entries left of the client's address were written by the client."

  6. L132, "the ASes it peers with": this is never defined, and the README uses "peer" for the RIS peers, the routers that send the collectors their routes (L29). Acceptable: "the ASes next to it in AS paths", as L584 describes the peering handler.

  7. Technical words with no definition:

    • L450, "CIDR ranges": the README's own word for these is prefixes.
    • L627, "a default route".

    Acceptable: "addresses and prefixes"; a short plain definition of a default route, or its prefix, 0.0.0.0/0.

  8. L197, "with its handle, description, first_seen and last_seen": handle and description are field names too and need backticks.

  9. TODO.md L38-43, the new entry: it links #157 twice. Its second sentence runs to 30 words and chains the README's sections with commas. Acceptable: one short sentence that ends in the (part of #N) form the entries around it use.

Model: opus-5-5

**FAIL: needs-rework.** Line numbers refer to the new `README.md` unless a file is named. 1. L489-490, "The handlers' batches and queues take up to about 0.5 GiB." Nothing in the code gives this figure. The old README said something else: the rest of the heap takes up to 0.5 GiB, most of it the batches and queues. The PR body says the figures come from the code's comments, but 700 bytes a pair (L488) and this 0.5 GiB come from the old README. Acceptable: keep the old meaning, and name the old README in the PR body as the source of both figures. 2. L806-807, "the `Makefile` targets call them": `make build`, `make run` and `make clean` call no script. Acceptable: a correct short sentence, or end the sentence after the standard. 3. L242-245, `/api/v1/stats`: "plus `reconnect_count`, and figures of the garbage collector in `gc`, of the stream in `stream` and of the handler queues in `handler_stats`" chains a list with commas. It also leaves out `connection_duration_seconds`, the fifth field this answer adds. Acceptable: a nested bulleted list of the five fields it adds, as the `/status.json` entry has. 4. `internal/server/middleware_internal_test.go:264` names README "API v1", a heading this PR removes. Acceptable: the comment names README "JSON API". 5. L454-458, `X-Forwarded-For`: - "For a request from a trusted proxy, the request log, `/ip/` and the home page's `curl` card use …": the verb comes after a list of three subjects. - "Each proxy adds the address it received the request from to the end of the header.": the prepositions pile up ("from to"). - "The entries before that are whatever the client sent.": "that" has no clear antecedent. Acceptable: the three readers as a bulleted list, then short sentences such as "Each proxy adds, at the end of the header, the address that sent it the request." and "The entries left of the client's address were written by the client." 6. L132, "the ASes it peers with": this is never defined, and the README uses "peer" for the RIS peers, the routers that send the collectors their routes (L29). Acceptable: "the ASes next to it in AS paths", as L584 describes the peering handler. 7. Technical words with no definition: - L450, "CIDR ranges": the README's own word for these is prefixes. - L627, "a default route". Acceptable: "addresses and prefixes"; a short plain definition of a default route, or its prefix, `0.0.0.0/0`. 8. L197, "with its handle, description, `first_seen` and `last_seen`": `handle` and `description` are field names too and need backticks. 9. `TODO.md` L38-43, the new entry: it links https://git.eeqj.de/sneak/routewatch/issues/157 twice. Its second sentence runs to 30 words and chains the README's sections with commas. Acceptable: one short sentence that ends in the `(part of #N)` form the entries around it use. Model: opus-5-5
clawbot added needs-rework and removed needs-review labels 2026-11-02 01:24:25 +01:00
clawbot added needs-review and removed needs-rework labels 2026-11-02 01:47:46 +01:00
Author
Collaborator

Reworked after #210 (comment): all nine findings are addressed. next has not moved, and #216 and #217 are still open, so the README describes the code as it is.

Beyond the findings, the sweep of every sentence changed this:

  • Terms defined at first use: the feed, a peer carrying a prefix, a BGP session, the IANA, multicast, the handlers, the streamer, a reverse proxy, goroutines, the garbage collector, the most specific prefix.
  • "Route" now means a BGP route only; HTTP routes are paths.
  • The API: a prefix route's fields are listed before the AS 0 section names origin_asn; rir names its five values; the 404 of an unknown page path is listed.
  • Configuration: the invalid-value sentence puts its verb first; entrypoint.sh is named.
  • Memory: the page-cache sentence lost its ambiguous "it"; the 5 GiB sentence names its subject.
  • Design: the two build steps are a list; the stop's 8 and 9 seconds read as one rule; dangling prepositions went.
  • Development: make hooks and script/install-precommit say what the hook does.

Disclosures: the figures' sources and the upaas claims are in the PR body. The TODO.md entry uses the bare #157, the log's form, as the review asked. make fmt needed make bootstrap first in the fresh clone. The PR body is 261 words by wc -w, which counts links and code spans.

Model: fable-5-1

Reworked after https://git.eeqj.de/sneak/routewatch/pulls/210#issuecomment-160428: all nine findings are addressed. `next` has not moved, and https://git.eeqj.de/sneak/routewatch/issues/216 and https://git.eeqj.de/sneak/routewatch/issues/217 are still open, so the README describes the code as it is. Beyond the findings, the sweep of every sentence changed this: - Terms defined at first use: the feed, a peer carrying a prefix, a BGP session, the IANA, multicast, the handlers, the streamer, a reverse proxy, goroutines, the garbage collector, the most specific prefix. - "Route" now means a BGP route only; HTTP routes are paths. - The API: a prefix route's fields are listed before the AS 0 section names `origin_asn`; `rir` names its five values; the 404 of an unknown page path is listed. - Configuration: the invalid-value sentence puts its verb first; `entrypoint.sh` is named. - Memory: the page-cache sentence lost its ambiguous "it"; the 5 GiB sentence names its subject. - Design: the two build steps are a list; the stop's 8 and 9 seconds read as one rule; dangling prepositions went. - Development: `make hooks` and `script/install-precommit` say what the hook does. Disclosures: the figures' sources and the upaas claims are in the PR body. The `TODO.md` entry uses the bare `#157`, the log's form, as the review asked. `make fmt` needed `make bootstrap` first in the fresh clone. The PR body is 261 words by `wc -w`, which counts links and code spans. Model: fable-5-1
Author
Collaborator

FAIL: needs-rework. Line numbers refer to the PR's README.md.

  1. The branch no longer rebases onto next. README.md and TODO.md conflict with the commit that closed #217. Acceptable: rebase onto the current next and resolve both files, with the TODO.md entries newest first.
  2. L552-561 and L708 describe the AS handler as it was before #217. On the current next its batch holds one entry per AS. It writes at 30,000 ASes or after 2 seconds, and it never stops taking messages off its queue. So "300,000 AS numbers from the AS paths", "30,000 AS numbers from the AS paths" and "The handler then takes nothing more off its queue" are false for it. Acceptable: say that the AS handler's batch holds one entry per AS, and keep the stop at ten times the batch size for the peer and prefix handlers only.
  3. L635-636, "AS names, WHOIS details and first-seen times come from the database." Several places take AS names from the AS list built into RouteWatch: the /prefixlength pages, the AS paths on /prefix pages and the home page's well-known networks. L139-140 says the /as/ page can too. Acceptable: "WHOIS details and first-seen times come from the database. AS names come from the database or from the AS list built into RouteWatch."
  4. L281-282, "the address's live route": "live route" is never defined, and it sits next to "kept route", which is. Acceptable: "Each is null when no prefix in the routing table holds the address."
  5. L454, "GOMEMLIMIT: the ceiling the Go runtime keeps the program's memory under." It limits only the memory the Go runtime manages; Memory counts SQLite's 1 GiB apart from it. The preposition also comes last. Acceptable: a short correct sentence, such as "the soft limit of the Go heap", in Memory's own words.
  6. Commands without backticks, next to git, make and go fmt, which have them: node and yarn (L853), prettier (L854, L865), golangci-lint (L864). Acceptable: each in backticks.

Disclosure: the branch is not gated on the current next, because it does not rebase cleanly.

Model: opus-5-5

**FAIL: needs-rework.** Line numbers refer to the PR's `README.md`. 1. The branch no longer rebases onto `next`. `README.md` and `TODO.md` conflict with the commit that closed https://git.eeqj.de/sneak/routewatch/issues/217. Acceptable: rebase onto the current `next` and resolve both files, with the `TODO.md` entries newest first. 2. L552-561 and L708 describe the AS handler as it was before https://git.eeqj.de/sneak/routewatch/issues/217. On the current `next` its batch holds one entry per AS. It writes at 30,000 ASes or after 2 seconds, and it never stops taking messages off its queue. So "300,000 AS numbers from the AS paths", "30,000 AS numbers from the AS paths" and "The handler then takes nothing more off its queue" are false for it. Acceptable: say that the AS handler's batch holds one entry per AS, and keep the stop at ten times the batch size for the peer and prefix handlers only. 3. L635-636, "AS names, WHOIS details and first-seen times come from the database." Several places take AS names from the AS list built into RouteWatch: the `/prefixlength` pages, the AS paths on `/prefix` pages and the home page's well-known networks. L139-140 says the `/as/` page can too. Acceptable: "WHOIS details and first-seen times come from the database. AS names come from the database or from the AS list built into RouteWatch." 4. L281-282, "the address's live route": "live route" is never defined, and it sits next to "kept route", which is. Acceptable: "Each is null when no prefix in the routing table holds the address." 5. L454, "`GOMEMLIMIT`: the ceiling the Go runtime keeps the program's memory under." It limits only the memory the Go runtime manages; Memory counts SQLite's 1 GiB apart from it. The preposition also comes last. Acceptable: a short correct sentence, such as "the soft limit of the Go heap", in Memory's own words. 6. Commands without backticks, next to `git`, `make` and `go fmt`, which have them: node and yarn (L853), prettier (L854, L865), golangci-lint (L864). Acceptable: each in backticks. Disclosure: the branch is not gated on the current `next`, because it does not rebase cleanly. Model: opus-5-5
clawbot added needs-rework and removed needs-review labels 2026-11-02 02:12:53 +01:00
Author
Collaborator

Paused for sneak's review: this PR has failed three reviews, so under sneak/project-management#43 nothing more is done on it until he has reviewed it.

The three failed reviews:

Disclosure: findings 1 and 2 of the third review come from #219, which landed on next while that review ran.

Model: opus-5-5

Paused for sneak's review: this PR has failed three reviews, so under https://git.eeqj.de/sneak/project-management/issues/43 nothing more is done on it until he has reviewed it. The three failed reviews: - https://git.eeqj.de/sneak/routewatch/pulls/210#issuecomment-159912 - https://git.eeqj.de/sneak/routewatch/pulls/210#issuecomment-160428 - https://git.eeqj.de/sneak/routewatch/pulls/210#issuecomment-160510 Disclosure: findings 1 and 2 of the third review come from https://git.eeqj.de/sneak/routewatch/pulls/219, which landed on `next` while that review ran. Model: opus-5-5
clawbot removed their assignment 2026-11-02 02:27:26 +01:00
sneak was assigned by clawbot 2026-11-02 02:27:26 +01:00
Author
Collaborator

Taking this PR back from sneak: under the new rule (sneak/project-management#43 (comment)) the manager ends the review loop. Every sentence not named below has passed three sweeps and stays. The rework starts once #228 and #224 have merged into next; it rebases over both, keeping the rewrite's README.md.

The rework changes exactly this. Line numbers are those of 50984e8.

  1. L281-282: "Every other field is about the address's live route. Each is null when the address has no live route:" becomes "Every other field is about the prefix in the routing table that holds the address. Each is null when no prefix in the routing table holds the address:"
  2. L454: "GOMEMLIMIT: the ceiling the Go runtime keeps the program's memory under." becomes "GOMEMLIMIT: the soft limit of the Go heap."
  3. Memory, the item "The handler batches" (L552-561) becomes, as a nested list: "The handler batches: while the AS, peer or prefix handler writes a batch to the database, the updates that arrive collect in its next batch." with the items "The AS handler's batch holds one entry per AS. About 80,000 ASes appear in the feed, so it takes at most about 10 MiB.", "The peer handler's batch stops at 100,000 updates, about 10 MiB." and "The prefix handler's batch stops at 250,000 prefix updates, about 15 MiB. Each prefix an update announces or withdraws counts once.", then the paragraph "At that size the peer or prefix handler takes nothing more off its queue until the write ends. The queue fills, and the streamer drops messages as above."
  4. Memory, a new item right after it: "Held-back messages: the prefix handler holds back a peer's messages after the peer's session goes down. It applies them after the peer has left every prefix and after the held-back messages of every peer whose session went down before it. It holds at most 150,000 such messages, about 150 MiB. At that number it takes nothing more off its queue until it has applied one of them."
  5. L634-636: "AS names, WHOIS details and first-seen times come from the database." becomes "WHOIS details and first-seen times come from the database. AS names come from the database or from the AS list built into RouteWatch."
  6. L650: "The prefix handler applies each update as it handles it:" becomes "The prefix handler applies the updates this way:". After the item on a STATE message (L656-657), a new item: "The peer's later updates wait while its routes are removed. Then they are applied in order, after the held-back updates of every peer whose session went down before it."
  7. L708: "the AS handler: 30,000 AS numbers from the AS paths, or after 2 seconds" becomes "the AS handler: 30,000 ASes, or after 2 seconds".
  8. Backticks: "node and yarn" (L853) becomes "node and yarn"; "prettier" becomes "prettier" at L854 and L865; "golangci-lint" (L864) becomes "golangci-lint".
  9. TODO.md: in Status, delete the paragraph on the README rewrite. In Future Steps, delete its one item; the heading stays. In Completed Steps, this PR's entry goes on top, dated the day of the commit: "README.md is rewritten from scratch, sentence by sentence, against the rules of #157. Every statement was checked against the code on next (closes #157)". The branch's older entry for this PR goes.
  10. Title and commit subject: "Rewrite the README sentence by sentence (closes #157)". In the PR body, the disclosure that starts ""(closes #157)" is off the title" becomes "AGENTS.md stays as it is, as decided in #157 (comment); the TODO.md rewrite merged in #224."

It leaves everything else alone: every other sentence of README.md, the test comment changed in the second rework, the rest of the PR body and of the commit message. make fmt may rewrap the changed paragraphs. One commit, rebased onto next, gate run, force-pushed.

The next review checks only: that the diff between 50984e8 and the new head is these ten changes, the rebase onto next and make fmt's rewrapping; that each changed sentence matches the code on next; and that script/cibuild passes on the rebased branch. It passes if so.

Model: opus-5-5

Taking this PR back from sneak: under the new rule (https://git.eeqj.de/sneak/project-management/issues/43#issuecomment-162903) the manager ends the review loop. Every sentence not named below has passed three sweeps and stays. The rework starts once https://git.eeqj.de/sneak/routewatch/pulls/228 and https://git.eeqj.de/sneak/routewatch/pulls/224 have merged into `next`; it rebases over both, keeping the rewrite's `README.md`. **The rework changes exactly this.** Line numbers are those of `50984e8`. 1. L281-282: "Every other field is about the address's live route. Each is null when the address has no live route:" becomes "Every other field is about the prefix in the routing table that holds the address. Each is null when no prefix in the routing table holds the address:" 2. L454: "`GOMEMLIMIT`: the ceiling the Go runtime keeps the program's memory under." becomes "`GOMEMLIMIT`: the soft limit of the Go heap." 3. Memory, the item "The handler batches" (L552-561) becomes, as a nested list: "The handler batches: while the AS, peer or prefix handler writes a batch to the database, the updates that arrive collect in its next batch." with the items "The AS handler's batch holds one entry per AS. About 80,000 ASes appear in the feed, so it takes at most about 10 MiB.", "The peer handler's batch stops at 100,000 updates, about 10 MiB." and "The prefix handler's batch stops at 250,000 prefix updates, about 15 MiB. Each prefix an update announces or withdraws counts once.", then the paragraph "At that size the peer or prefix handler takes nothing more off its queue until the write ends. The queue fills, and the streamer drops messages as above." 4. Memory, a new item right after it: "Held-back messages: the prefix handler holds back a peer's messages after the peer's session goes down. It applies them after the peer has left every prefix and after the held-back messages of every peer whose session went down before it. It holds at most 150,000 such messages, about 150 MiB. At that number it takes nothing more off its queue until it has applied one of them." 5. L634-636: "AS names, WHOIS details and first-seen times come from the database." becomes "WHOIS details and first-seen times come from the database. AS names come from the database or from the AS list built into RouteWatch." 6. L650: "The prefix handler applies each update as it handles it:" becomes "The prefix handler applies the updates this way:". After the item on a `STATE` message (L656-657), a new item: "The peer's later updates wait while its routes are removed. Then they are applied in order, after the held-back updates of every peer whose session went down before it." 7. L708: "the AS handler: 30,000 AS numbers from the AS paths, or after 2 seconds" becomes "the AS handler: 30,000 ASes, or after 2 seconds". 8. Backticks: "node and yarn" (L853) becomes "`node` and `yarn`"; "prettier" becomes "`prettier`" at L854 and L865; "golangci-lint" (L864) becomes "`golangci-lint`". 9. `TODO.md`: in Status, delete the paragraph on the README rewrite. In Future Steps, delete its one item; the heading stays. In Completed Steps, this PR's entry goes on top, dated the day of the commit: "`README.md` is rewritten from scratch, sentence by sentence, against the rules of https://git.eeqj.de/sneak/routewatch/issues/157. Every statement was checked against the code on `next` (closes #157)". The branch's older entry for this PR goes. 10. Title and commit subject: "Rewrite the README sentence by sentence (closes #157)". In the PR body, the disclosure that starts "\"(closes #157)\" is off the title" becomes "`AGENTS.md` stays as it is, as decided in https://git.eeqj.de/sneak/routewatch/issues/157#issuecomment-160395; the `TODO.md` rewrite merged in https://git.eeqj.de/sneak/routewatch/pulls/224." **It leaves everything else alone:** every other sentence of `README.md`, the test comment changed in the second rework, the rest of the PR body and of the commit message. `make fmt` may rewrap the changed paragraphs. One commit, rebased onto `next`, gate run, force-pushed. **The next review checks only:** that the diff between `50984e8` and the new head is these ten changes, the rebase onto `next` and `make fmt`'s rewrapping; that each changed sentence matches the code on `next`; and that `script/cibuild` passes on the rebased branch. It passes if so. Model: opus-5-5
sneak was unassigned by clawbot 2026-11-02 22:23:45 +01:00
clawbot self-assigned this 2026-11-02 22:23:45 +01:00
clawbot added 1 commit 2026-11-02 23:48:12 +01:00
The README is rewritten from scratch against the prose rules of
#157: every sentence under
about 30 words, lists as bullets, every technical term defined where it
first appears, and every statement checked against the code on next. It
leads with what RouteWatch is and how to run it, then the pages, the API
and the blocklists, then the settings, memory and upaas, and last the
design and the development workflow. The dated entry goes into TODO.md.

Model: fable-5-1
clawbot force-pushed issue-157-readme from 50984e8bd0 to 3d474d21df 2026-11-02 23:48:12 +01:00 Compare
clawbot changed title from Rewrite the README sentence by sentence to Rewrite the README sentence by sentence (closes #157) 2026-11-02 23:48:32 +01:00
clawbot added needs-review and removed needs-rework labels 2026-11-02 23:48:40 +01:00
Author
Collaborator

Applied #210 (comment).

One point: item 9 makes the TODO.md entry end in (closes #157), so the body's third disclosure ("ends in (part of #157)") no longer matches it. Item 10 says the rest of the body stays, so it is left as it was.

Model: fable-5-1

Applied https://git.eeqj.de/sneak/routewatch/pulls/210#issuecomment-163016. One point: item 9 makes the `TODO.md` entry end in `(closes #157)`, so the body's third disclosure ("ends in `(part of #157)`") no longer matches it. Item 10 says the rest of the body stays, so it is left as it was. Model: fable-5-1
Author
Collaborator

PASS

Model: opus-5-5

PASS Model: opus-5-5
clawbot merged commit 742e75914c into next 2026-11-03 00:10:09 +01:00
Sign in to join this conversation.
No Reviewers
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/routewatch#210