From 357a291ae794acc74fa6a075f5e21d4d9494a5ab Mon Sep 17 00:00:00 2001 From: harishghasolia07 <100846446+harishghasolia07@users.noreply.github.com> Date: Wed, 26 Aug 2026 05:21:43 +0000 Subject: [PATCH] Close four first-run gaps a cold reader hits in the README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cc29640..c2881d5 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ writes out, with human-in-the-loop gates on everything it is not sure about. *Real captured output, replayed at reading speed — the actual run takes under a second. Nothing above is staged.* ```bash +git clone https://github.com/agentloopr/Triage.git && cd Triage npm ci npm run demo # 8 scenarios, offline, under a second, no API key npm run demo -- --twice # a redelivery costs zero tokens @@ -104,6 +105,20 @@ npm run demo -- --provider anthropic # the same scenarios, replayed from a Cla npm run demo -- --agents # with the agent layer on (see AGENTS.md), also offline ``` +`--twice` is the one worth running second. The second pass prints: + +``` +✓ re-run: skipped at layer 'event' — 0 model calls, $0.00 +``` + +A redelivery costs nothing, and the check that stops it runs *before* the first token is spent +rather than discarding a finished run at the end. + +**`--board-writes` has no recorded cassettes and will not replay offline.** The flag is real (see +[AGENTS.md](AGENTS.md)), but recording that mode needs live API keys against both providers, so +`npm run demo -- --agents --board-writes` stops on a missing cassette rather than running green +having done nothing. That error is the intended behaviour, not a broken build. + ``` ▶ 01-meeting-mixed — A normal standup: four categories exercised, four cards created, one duplicate skipped, and a post-write audit that confirms the board matches the plan. @@ -229,11 +244,15 @@ taxonomy is tracker-blind because of it. ## Documentation +**If you read two of these, read `LIMITATIONS.md` and `EXTRACTION.md`.** The first is what this repo +cannot tell you; the second is what differs from the system it came out of. They are the two that +tell you whether to trust the other six. + | | | |---|---| | [ARCHITECTURE.md](ARCHITECTURE.md) | The passes, the seams, idempotency, fail-open vs fail-closed | | [LIMITATIONS.md](LIMITATIONS.md) | **What this cannot tell you.** Read before trusting a green run | -| [EXTRACTION.md](EXTRACTION.md) | What differs from production, what was de-tuned, and how it was checked | +| [EXTRACTION.md](EXTRACTION.md) | **What differs from the system this came out of**, what was de-tuned, and how it was verified | | [ADAPTERS.md](ADAPTERS.md) | The tracker contract, the capability matrix, writing a fourth | | [PROVIDERS.md](PROVIDERS.md) | Measured cost, and where DeepSeek and Claude disagree | | [ROLES.md](ROLES.md) | The eight role archetypes and how they reach the prompt |