Keep the presentation of loop-claude, with the script that prints it to PDF and what writing it settled
CI / tests (pull_request) Successful in 2m15s

This commit is contained in:
2026-11-09 23:05:33 +01:00
parent 6fdf7d28a5
commit 46fc4dde7c
6 changed files with 1151 additions and 1 deletions
+5
View File
@@ -106,6 +106,11 @@
!bin/transcript_archive/*.py
!docs/
!docs/*.md
!presentation/
!presentation/README.md
!presentation/build-pdf.sh
!presentation/index.html
!presentation/render-pdf.js
!principles/
!principles/*.md
!reviewer-merge-trials/
+1 -1
View File
@@ -1,6 +1,6 @@
# Claude Code configuration
My personal `~/.claude`, version controlled: `CLAUDE.md`, `AGENTS.md` and `rules/` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `agents/` and `skills/`; `principles/` and `skills/larv-review/standards/` for what the reviewer agents hold projects to; `docs/` for decisions and the comprehension history; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`; `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review; and `reviewer-merge-trials/`, the 2026-11-09 trials of merging reviewers, with their method, results and scripts.
My personal `~/.claude`, version controlled: `CLAUDE.md`, `AGENTS.md` and `rules/` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `agents/` and `skills/`; `principles/` and `skills/larv-review/standards/` for what the reviewer agents hold projects to; `docs/` for decisions and the comprehension history; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`; `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review; `reviewer-merge-trials/`, the 2026-11-09 trials of merging reviewers, with their method, results and scripts; and `presentation/`, a page that explains this setup to newcomers, with the script that prints it to PDF.
## Goals
+59
View File
@@ -0,0 +1,59 @@
# presentation
`index.html` explains loop-claude, in 22 pages, to developers who have never seen an agent loop. It is published as a claude.ai artifact and printed to an A4 landscape PDF.
## Rebuild the PDF
```sh
presentation/build-pdf.sh
```
It writes `presentation/loop-claude-explained.pdf`, which stays out of git. It needs Docker and the `playwright-for-claude` image, which `~/code/playwright-for-agents/pw about:blank` builds once.
`index.html` is an artifact body: it has no doctype, head or body of its own. `build-pdf.sh` wraps it the way the artifact host does. To publish an edited page, publish `index.html` to the same artifact.
## Who it is for
People in tech who want to build software factories, work with AI tools more efficiently, and stop fighting their agents. They know git, pull requests and the shell, and nothing about agent loops. Write for a tired reader on a Monday morning without coffee: one fact per sentence, each term explained before it is used, and no filler.
## 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.
- **Three sections:**
- **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.
- **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.
## Where the figures come from
The figures were current on 2026-11-09. Update 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.
- **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.
## 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`.
+25
View File
@@ -0,0 +1,25 @@
#!/bin/sh
# Print index.html to loop-claude-explained.pdf beside it, in the playwright-for-claude image.
# The image comes from ~/code/playwright-for-agents: its ./pw builds it on first use.
set -eu
here=$(cd "$(dirname "$0")" && pwd)
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
if ! docker image inspect playwright-for-claude >/dev/null 2>&1; then
echo "No playwright-for-claude image. Build it once with: ~/code/playwright-for-agents/pw about:blank" >&2
exit 1
fi
# index.html is an artifact body, without a doctype, head or body of its own, so wrap it as the artifact host does.
{
printf '<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"><style>:root{color-scheme:light}body{margin:0}img{max-width:100%%}[hidden]{display:none!important}</style></head><body>\n'
cat "$here/index.html"
printf '</body></html>\n'
} > "$work/page.html"
cp "$here/render-pdf.js" "$work/"
docker run --rm --init --memory 2g --memory-swap 2g -v "$work:/work" -w /work --entrypoint node playwright-for-claude render-pdf.js
cp "$work/out.pdf" "$here/loop-claude-explained.pdf"
echo "Wrote $here/loop-claude-explained.pdf"
File diff suppressed because it is too large Load Diff
+14
View File
@@ -0,0 +1,14 @@
// Print /work/page.html to /work/out.pdf with Chromium, as build-pdf.sh runs it inside the playwright-for-claude image.
const { chromium } = require('/app/node_modules/playwright');
(async () => {
const browser = await chromium.launch({ args: ['--no-sandbox', '--disable-dev-shm-usage'] });
const page = await browser.newPage({ viewport: { width: 1100, height: 1400 } });
// networkidle waits for the Google Fonts the page loads; fonts.ready waits for them to apply.
await page.goto('file:///work/page.html', { waitUntil: 'networkidle' });
await page.evaluate(() => document.fonts.ready);
await page.emulateMedia({ media: 'print' });
// preferCSSPageSize takes the page's own @page rule: A4 landscape.
await page.pdf({ path: '/work/out.pdf', format: 'A4', printBackground: true, preferCSSPageSize: true });
await browser.close();
})();