Answer product-owner round 1: 0 🔴, 3 🟡 (0 misread); say where the page is published and how, give the commands behind each figure and the network the build needs, point the step list at page 3, list MultiEdit, and name independent work in source 7; prose's README fixes ride along

This commit is contained in:
2026-11-09 23:13:31 +01:00
parent c2792f684a
commit 6a85249d99
2 changed files with 24 additions and 23 deletions
+20 -19
View File
@@ -8,9 +8,13 @@
presentation/build-pdf.py
```
It writes `presentation/loop-claude-explained.pdf`, which stays out of git. It needs Docker and the `playwright-for-claude` image. Build the image once with `~/.claude/bin/run-heavy docker build -t playwright-for-claude ~/code/playwright-for-agents`.
It writes `presentation/loop-claude-explained.pdf`, which stays out of git. It needs Docker, network access to Google Fonts, and the `playwright-for-claude` image. Build the image once with `~/.claude/bin/run-heavy docker build -t playwright-for-claude ~/code/playwright-for-agents`. When a font fails to load, the build stops without printing: fallback fonts would push pages onto a second sheet.
`index.html` is an artifact body: it has no doctype, head or body of its own. `build-pdf.py` wraps it the way the artifact host does. To publish an edited page, publish `index.html` to the same artifact.
## Publish the page
The page lives at https://claude.ai/artifact/RJJwgRAke3viuqTYEgu1a9. To update it, ask Claude Code to publish `presentation/index.html` to that URL with its Artifact tool; the tool reads the live version first.
`index.html` is an artifact body: it has no doctype, head or body of its own. `build-pdf.py` wraps it the way the artifact host does.
## Who it is for
@@ -18,8 +22,6 @@ People in tech who want to build software factories, work with AI tools more eff
## How the pages are built
These choices were made with the human while the pages were written.
- **Page 1 engages.** It states the problem, what loop-claude does, what it aims for, who it is for, and three real figures.
- **Pages 2 and 3 share one layout.** Page 2 is the simple chart, page 3 the full one. The section frames, the human boxes, the colours and the return arrows sit in the same places on both. Each big box on page 2 is the group of steps at the same place on page 3, so a reader translates by position. Keep it that way.
- **The full chart shows every piece.** A simpler view may group pieces, never drop them.
@@ -27,33 +29,32 @@ These choices were made with the human while the pages were written.
- **A · Start, deterministic, no AI:** Rank the plan, Prepare, Pick the work, Pick model.
- **B · Work, the worker:** Build, Review, Gate, Goals check, Readability, Merge. The release review sits on top, and new items flow back into the plan.
- **C · Check, the judge:** its verdicts, and where each one returns.
- **The human stands outside the sections,** since a human is not deterministic. Planning a release is a chunk in B: the worker drafts it, and the human approves it.
- **The human stands outside the sections,** since the human is not a step the loop runs. Planning a release is a chunk in B: the worker drafts it, and the human approves it.
- **Zoom pages break one section down, one page each,** with the same step names. They never cut the flow another way.
- **Colours mean roles:** amber the human, blue the worker, violet the judge, teal the reviewers, green the merge.
- **Each page fits one landscape A4 sheet.** After an edit, rebuild the PDF and check the page count: a page that spills shows up as an extra page.
- **Draw arrows after the section backgrounds,** or a section box hides them.
- **Every page ends with "Why: sources …",** linking to the numbered rows of the "Why it works this way" pages. Each row is tagged Research, Book, Vendor docs, Benchmark, Own measurement, Experience or Reasoning.
- **Pages 2 to 17 each carry a "Why: sources …" line,** linking to the numbered rows of the "Why it works this way" pages. Each row is tagged Research, Book, Vendor docs, Benchmark, Own measurement, Experience or Reasoning.
## Where the figures come from
The figures were current on 2026-11-09. Update them before presenting again.
The figures were current on 2026-11-09. Refresh them before presenting again.
- **362 finished chunks and 17 projects:** loop-claude's archive, which starts on 2026-10-04. Count the `*.outcomes.md` files holding `Verdict: finished`, and the project folders.
- **2,526 commits:** `git log --oneline | wc -l` in this repo.
- **Finished chunks, 466 since 2026-10-03,** in loop-claude's archive:
```sh
find ~/.claude/loop-claude-transcripts -name '*.outcomes.md' -exec grep -l 'Verdict: finished' {} + | wc -l
```
The first stamp in any outcomes file gives the start date.
- **Projects that finished a chunk, 12.** Each archive folder holding `.outcomes.md` files is a project key. Count the keys with a finished chunk, and count `claude-config` and `home/lilleman/.claude` as one project: the second is this repo's release checkout.
- **Commits, 2,538:** `git log --oneline | wc -l` in this repo.
- **The readability bars:** the latest scoring run in `docs/comprehension-history.md`, the rerun on PR #397.
- **The two plan rows:** items 281 and 286 of `todo.md`.
- **Every other figure:** `docs/decisions.md`, `docs/scoring-and-goals-research.md` and `reviewer-merge-trials/README.md`.
Two sources appear only here, as reading in support of a fresh context per chunk: Liu et al., "Lost in the Middle", TACL 2024; and Hong et al., "Context Rot", Chroma Research, 2025.
Two sources in row 1 are cited nowhere else in the repo, as reading in support of a fresh context per chunk: Liu et al., "Lost in the Middle", TACL 2024; and Hong et al., "Context Rot", Chroma Research, 2025.
## Checking it
A subagent fact-checked the whole page against this repo on 2026-11-09. It found 24 errors, and all are fixed. Run such a check again after a larger edit, since the setup changes under the page.
## What writing it changed
Explaining the setup raised questions the repo now answers:
- PR #455: code health holds for years, and goal 1.4 keeps lowering cost, with a rising reading cost as its first counter-signal.
- PR #456: `reviewer-merge-trials/`, and the decision `review: each pass keeps a reviewer of its own`.
- Items 288, 289 and 290 in `todo.md`.
After a larger edit, fact-check the page against the repo again: the setup changes under it.
+4 -4
View File
@@ -469,7 +469,7 @@ dl.gloss dt { font-weight: 700; } dl.gloss dd { margin: 0; color: var(--muted);
<li><code>skills/comprehension-panel/</code> <span>the simulated readers</span></li>
<li><code>principles/</code> <span>technical principles reviewers hold code to</span></li>
<li><code>bin/</code> <span>the tools: <code>loop-claude</code>, <code>loop-inbox</code>, <code>chunk-preflight</code>, <code>chunk-pr</code>, <code>rule-hook</code>, <code>rank_todo.py</code>, <code>run-heavy</code> and more</span></li>
<li><code>settings.json</code> <span>runs <code>rule-hook</code> before each Agent, Bash, Edit, Read, Skill and Write call</span></li>
<li><code>settings.json</code> <span>runs <code>rule-hook</code> before each Agent, Bash, Edit, MultiEdit, Read, Skill and Write call</span></li>
</ul>
</div>
<div class="col" style="border-top-color:var(--judge)">
@@ -538,7 +538,7 @@ dl.gloss dt { font-weight: 700; } dl.gloss dd { margin: 0; color: var(--muted);
<section class="page" id="chunk">
<div class="eyebrow">Zoom in: B · Work</div>
<h2>B · Work, in detail</h2>
<p class="lead">The worker follows a fixed recipe, called <b>larv-review</b>. The same six steps as page 1.</p>
<p class="lead">The worker follows a fixed recipe, called <b>larv-review</b>. The same six steps as page 3.</p>
<div class="diagram" role="img" aria-label="Build: a test that fails first, the simplest code, a draft PR. Then review, gate, goals check, readability and merge.">
<svg viewBox="0 0 1090 150">
<g>
@@ -938,7 +938,7 @@ dl.gloss dt { font-weight: 700; } dl.gloss dd { margin: 0; color: var(--muted);
<thead><tr><th>Rail</th><th>What it does</th></tr></thead>
<tbody>
<tr><td>Sandbox</td><td>Runs only on a dedicated machine, such as a VM, with no access to production. Claude Code skips permission prompts there.</td></tr>
<tr><td><code>rule-hook</code></td><td>Runs before each Agent, Bash, Edit, Read, Skill and Write call. Blocks e.g. multi-line commit messages, unpinned images, containers without memory limits, a third review round. Some rules allow a written override; the Overrides reviewer judges each one.</td></tr>
<tr><td><code>rule-hook</code></td><td>Runs before each Agent, Bash, Edit, MultiEdit, Read, Skill and Write call. Blocks e.g. multi-line commit messages, unpinned images, containers without memory limits, a third review round. Some rules allow a written override; the Overrides reviewer judges each one.</td></tr>
<tr><td><code>run-heavy</code></td><td>Heavy commands (builds, mutation tests, full test runs) wait for a shared slot: one per 4 CPUs on the machine.</td></tr>
<tr><td>Memory</td><td>Every container gets a memory limit. A new worker starts only while a quarter of the machine's memory is free.</td></tr>
<tr><td>Context</td><td>Each worker session, the <code>/talk</code> session and their subagents compact their context at about 170k tokens, keeping what the chunk still needs.</td></tr>
@@ -970,7 +970,7 @@ dl.gloss dt { font-weight: 700; } dl.gloss dd { margin: 0; color: var(--muted);
<tr id="src-4"><td>4</td><td><b>Every answer is written down</b></td><td><span class="kind x">Reasoning</span> A finished chunk's session is deleted. An answer kept nowhere else would be asked again in a later chunk. One goal of the setup is to never ask the same thing twice.</td></tr>
<tr id="src-5"><td>5</td><td><b>A program enforces every rule it can check</b></td><td><span class="kind r">Vendor docs</span> Anthropic's best-practices page calls <code>CLAUDE.md</code> advisory and hooks deterministic. So <code>rule-hook</code> blocks a rule-breaking tool call before it lands, in every project.<br><span class="kind m">Own measurement</span> The override marker's spelling was picked by a panel of three fresh readers, two to one.</td></tr>
<tr id="src-6"><td>6</td><td><b>Rules load by topic, not all at once</b></td><td><span class="kind r">Research</span> Anthropic's memory docs say a longer <code>CLAUDE.md</code> reduces adherence. IFScale (arXiv:2507.11538) measures adherence falling as the number of instructions grows. So each topic's rules load only when a matching file is touched.</td></tr>
<tr id="src-7"><td>7</td><td><b>The worker delegates only searches</b></td><td><span class="kind m">Own measurement</span> A subagent's report cost a median 8% of the worker's peak context. Search output (<code>sed</code>, <code>grep</code>) was 41% of its shell results. So searches go to subagents; edits stay with the worker, which would re-read a delegated diff anyway.</td></tr>
<tr id="src-7"><td>7</td><td><b>The worker hands subagents only searches and independent work</b></td><td><span class="kind m">Own measurement</span> A subagent's report cost a median 8% of the worker's peak context. Search output (<code>sed</code>, <code>grep</code>) was 41% of its shell results. So searches, and work independent enough to run in parallel, go to subagents; edits stay with the worker, which would re-read a delegated diff anyway.</td></tr>
<tr id="src-8"><td>8</td><td><b>A limit on how much the worker reads at once</b></td><td><span class="kind m">Own measurement</span> Under "no more than 80 lines of a file, or 3,000 characters of output, at once", three test tasks read 45–60% less, at the same or lower cost, every task done as well.</td></tr>
</tbody></table></div>
</section>