README: close four first-run gaps, and surface the three defects that shaped the repo - #20
Merged
Merged
Conversation
Walked the repo as someone who had just been sent the link, and hit four places where something true was documented but not where a five-minute skim would find it: - The opening code block started at `npm ci`, assuming a clone that no line ever told you to make. Every other instruction was complete; this one was not. - `--twice` was listed with its claim but not its payoff. The line it actually prints — "0 model calls, $0.00" — is the most quotable proof in the repo and was invisible until you ran it. - The documentation table gave eight files equal weight. LIMITATIONS.md had a bold hint; EXTRACTION.md did not, and it is the one that answers "is this really what you run?" - BOARD_AGENT_WRITES is documented in three places, so a reader will find the flag and try the obvious `--agents --board-writes`. That mode has no cassettes and stops on a missing one, which is correct behaviour and read as a broken build, because nothing said so first. Both quoted outputs are copied from a real run rather than written from memory.
digitalmasterykit-rgb
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two related passes over the README, both from walking it as a first-time reader who had just been
sent the link.
1. Four first-run gaps
None are wrong claims — they are gaps between "documented somewhere" and "obvious on arrival".
npm ci, assuming a clone no line tells you to makegit cloneline--twicelisted with its claim but not its payoff✓ re-run: skipped at layer 'event' — 0 model calls, $0.00EXTRACTION.mdnow carries the weightLIMITATIONS.mdhadBOARD_AGENT_WRITESand tries--agents --board-writes2. "Three things that went wrong"
A demo proves the code runs. It cannot prove anyone has run it — and the evidence that this has been
operated was already here, scattered across three files a five-minute reader never reaches.
Now surfaced in one place: the in-process lock that only fails when real processes race (
5a3ae48,20 of 20 workers wrongly accepting the same delivery), the
resumeHoldpath that was written, tested,correct and called by nothing, and the model-call counter that was measured, reproducible, and
under-reporting paid calls by a fifth.
Framed as what went wrong rather than as an argument about honesty — a section announcing its own
candour is the tell it is trying to avoid.
No new claims. Every figure is quoted from the file that already carried it, and each was checked
against its source before being repeated.
Verification
npm test— 1018 passing ·npm run lintclean5a3ae48confirmed reachable fromorigin/main--twiceand--board-writesoutputs) verified against their sources or a live run