docs(runbook): correct the v0.69 pass's findings — 127.0.0.1 baseline, design re-shoots, the stale-build trap, rig reproducibility - #832
Conversation
…ap, and rig reproducibility
Deploying paddock with
|
| Latest commit: |
035b3fc
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://e6f3d352.paddock-7u2.pages.dev |
| Branch Preview URL: | https://docs-runbook-v069-correction.paddock-7u2.pages.dev |
|
Closing — superseded by #830, which covers all four of these corrections and goes further (positive-control greps, CDN mid-propagation, One factual note for #830's author, since it lands in the cautionary example and would teach the wrong lesson if it ships as written. #830 says the previous revision "had the right total but attributed all 46 to the docs subtree and then added 'plus 6 in
The 38 was genuinely site-only and correct — not a mis-attributed 46, and the old text summed to 44, not 52. The single error was That also inverts the failure mode. A 52 over-count would hide a real hit (dangerous). The actual under-count by one produces a surplus unexplained hit, which is the safe direction — you investigate and find it legitimate. The lesson the real data supports, and which I think is worth keeping: if your own PR edits any of the files you are counting, count at the end, not the start. The baseline was stale before it was pushed. Repro: for r in 38075e0 38075e0^ origin/main; do
t=$(mktemp -d); git archive $r website/src/content/docs README.md | tar -x -C $t
echo "$r site=$(grep -ro '127\.0\.0\.1' $t/website/src/content/docs | wc -l) readme=$(grep -o '127\.0\.0\.1' $t/README.md | wc -l)"
rm -rf $t
doneMinor second point: the site count did not drift by much and why is instructive — it went 38 → 39 from one new file ( #830's totals (46 = 39 + 7) are correct and match my independent recount. |
…d re-checking state Both are about how this pass itself went wrong, which makes them the most valuable lessons in it. 'Verify a survey agent's NEGATIVE findings before acting on them' is the sharper one. A confident claim about what the code does NOT do reads as rigour, and is the one class of finding whose consequence is deleting correct documentation — nothing downstream catches it, because the edit makes the docs claim less, so it builds, reads sensibly and survives review. 'Re-check PR and issue state at the moment you act on it' covers the other concurrency hazard: several agents work this repo at once, so recon has a shelf life measured in hours.
The last-but-one figure was stale before it was pushed: the commit that recorded it (#778) also closed two README gaps, one of which added the seventh 127.0.0.1. That is not drift afterwards — it is the recording PR invalidating its own count. Last item outstanding from the #830/#831/#832 reconciliation; everything else those branches carried is already here.
1 participant
Corrections to
DOCS-UPDATE-RUNBOOK.mdfrom running it at v0.66.2 → v0.69.0. Prose only — one file, no code, no assets.What changed
§7 — the
127.0.0.1baseline was stale (recounted: 46). Replaced the inline prose count with a per-file table. The interesting part is how it drifted, which is now recorded, because the previous figure was wrong in two different ways:README.md" — had a correct site count and a README count that was already wrong when it was written. The commit that wrote it (docs: triage the docs/ fork, move + correct the runbook, close two README gaps #778) also closed two README gaps, one of which added the seventh hit. The baseline was stale before it was pushed. Hence the new rule: if your own PR edits the files you are counting, count at the end.guides/running-as-a-service.md, new in feat(cli):paddock service install— run Paddock from login (#796) #804. Notably feat(cli)!: remove--here, and lead the docs with Discover (#798) #803's Discover-led rewrite ofgetting-started.md, one of the most loopback-dense pages on the site, left it at 6. "A big docs PR landed" is not a proxy for "the baseline moved".Verified at three commits (
38075e0,60f6ab5,origin/main) rather than taken on trust; occurrences and matching lines are equal today (46 = 46).§5 — how to handle a release that changes the design. This was the hardest judgement of the pass and the runbook had nothing on it. A What's New entry describes the release as it shipped, so a historical still showing the old UI is correct and re-shooting it rewrites history; a page describing current behaviour showing an obsolete UI is simply wrong. Bucket by the tense of the surrounding prose, not the directory — directory is a proxy that fails on exactly the dual-use assets cited from both a current page and an archive entry. For those, fork: new frame for the current page, byte-identical copy left in
whats-new/.§5 — the stale-build trap. Serving
dist/from a clone that predates the release means every "re-shot" frame is the old UI, and every downstream check still passes — rig up, seeding fine, leak scan clean, all shots captured. The only tell is a design nobody examines while concentrating on framing. Recorded the mitigation as a positive assertion against the served bundle rather than the git state of a directory: name a UI element only the new build can paint and look for it first. The v0.69 example (/config→ Appearance section, four theme cards) is kept as an illustration under a generalised rule.§5 — the rig's own fragility. Not every path on a dev box is on a persisted volume. A rig whose projects dir sat on a non-persisted path lost its entire projects tree on a container restart while its data dir survived — and that asymmetry is the dangerous part: it boots to zero projects plus orphaned job records, which reads as "empty instance" rather than "destroyed instance". Points at #828 as the fix (env-driven
serve.sh/seed.mjsundertools/docs-media/).§3 — verify a survey agent's negative findings against source before acting. A negative claim is the highest-risk kind: it sounds like rigour, and acting on it deletes correct documentation. In this pass an audit reported an accessibility floor as unenforced; source showed it was real, and three children were briefly steered into under-claiming a shipped feature. Also: scope a negative to its narrowest defensible form, because an over-broad negative in a filed issue discredits the true one next to it.
§1 / §9 — re-check PR and issue state at the moment you act on it. Several agents work this repo concurrently; a PR landed mid-pass and closed three issues an audit had just re-verified as open. Includes the
stateReasoncaveat — an issue closed asNOT_PLANNEDor as a duplicate is not a fixed one.Notes for the reviewer
websitejob will report green having built nothing.DOCS-UPDATE-RUNBOOK.mdis at the repo root, outside thewebsite/**+openapi-site/**CI path filter, so the docs-site build is skipped step-by-step and still shows a green tick. This PR gets no docs build — please don't read that check as validation. (§8 already documents this trap; this PR is an instance of it.)sk-ant-/ghp_strings in the file are pre-existing scan patterns, not values.