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
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.mdfiles holdingVerdict: finished, and the project folders. - 2,526 commits:
git log --oneline | wc -lin 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.mdandreviewer-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 decisionreview: each pass keeps a reviewer of its own. - Items 288, 289 and 290 in
todo.md.