Skip to content

R11 · Documentation review

Done 2026-10-27 · 27 findings: 0 blockers, 6 majors, 21 minors · 0 dropped · 7 questions for Thomas · 3 spikes proposed

What changed

  • New review file: docs/reviews/R11-docs.md. It holds:
  • Navigation: mkdocs.yml gets the entry "R11: documentation" under Reviews.
  • No spec and no page was edited. This is a review round (see the review rules in docs/reviews/README.md). The prompt also says "Do not edit pages".
  • At the time of writing, both changes are uncommitted on autopilot/integration at 8179bff ("chore(autopilot): start R11").

Why

The documentation is part of done for every step. Fifteen Progress pages, a landing page, figures, casts and a video were written in W0 and W1. R11 checks them against documentation-system.md, the spec that owns the docs. It also checks that the spec can be implemented with the tools in tools/docs, tools/diagrams and tools/media.

Prompt: next-phase.md · R11. It runs as an autopilot step: decision log, 2026-10-26, autopilot. The rubric used is documentation-system §4.2.

Evidence

How the round ran (from the round's header in the review file and the workers' run records):

Item Value
Commit read autopilot/integration, 2026-10-27
Reviewers doc-reviewer and ux-reviewer, in parallel, both read-only, scratch files only under /tmp/r11/. Both returned output, none failed.
doc-reviewer Fresh context. Reviewed the whole site against documentation-system.md. Re-ran three commands per W0 Progress page (rubric §4.2). Opened every figure PNG, extracted 5 frames from gate-review.mp4, replayed the four casts. Its own verdict on the site was changes, 10/14 (from the worker's run output, which is not stored in the repository).
ux-reviewer Built and served the site. Rendered the landing page with Playwright at 1440×900 and 390×844, in light and dark (full pages, folds, crops, focus captures), plus the Landing.dc.html board.
Build used by both uvx --with mkdocs-material mkdocs build --strict -d /tmp/r11/site: exit 0, 0 warnings
Raw output 27 findings: doc-reviewer 3 majors and 10 minors (DOC-101…DOC-113), ux-reviewer 3 majors and 11 minors (DOC-201…DOC-214)
Merge renumbered into one sequence. Two overlaps were folded into surviving findings, not removed: the versions/ footer link (DOC-113 and DOC-212 into DOC-013) and the hero story (DOC-205 hero part into DOC-008).
Merger's check every major was reproduced in the repository at merge time: commit ancestry, check.py source, front matter, journal, docs/index.md, extra.css, docs/assets/shots/, a dark render crop. 0 dropped.

The merge summary returned by the step's workers:

"blockers": 0, "majors": 6, "minors": 21, "dropped": 0

Counts, checked against the file's headings and findings table:

$ for s in blocker major minor; do printf "%s " $s; grep -c "^### DOC-[0-9]* · $s ·" docs/reviews/R11-docs.md; done
blocker 0
major 6
minor 21
$ grep -cE '^\| DOC-[0-9]+ \| (blocker|major|minor) \|' docs/reviews/R11-docs.md
27

Exit criterion. R11 is done when its review file exists. It is also the last file the wave W1 exit check in pipeline.yaml was waiting for:

$ ls docs/reviews/R1-consistency.md docs/reviews/R4-constraints.md docs/reviews/R5-security.md docs/reviews/R7-ui.md docs/reviews/R8-depictio.md docs/reviews/R9-landscape.md docs/reviews/R11-docs.md >/dev/null; echo "exit_check=$?"
exit_check=0

The link from the review file to this page. R11-docs.md links to ../progress/W1/R11.md. Before this page existed, the strict build failed on it:

$ uvx --with mkdocs-material mkdocs build --strict -d /tmp/r11-site
WARNING -  Doc file 'reviews/R11-docs.md' contains a link '../progress/W1/R11.md', but the target 'progress/W1/R11.md' is not found among documentation files.

Aborted with 1 warnings in strict mode!

With this page in place, the same command passes (see the PR's Checks).

Figures and media

None required (review step).

Findings and open questions

The five findings that matter most (the review file explains the choice):

  1. DOC-001 · major: two owners describe two different public landing pages. ui-spec §4.1 says "install the server" and lists GA4GH WES; Landing.dc.html shows pip install spectio && spectio serve, MCP and GA4GH WES. documentation-system §2 and docs/index.md say "nothing to install yet".
  2. DOC-002 · major: the docs gate, tools/docs/check.py, reports "0 failure(s)" for three checks it does not run:
    • media referenced from pages are never parsed;
    • nothing checks the required pages per step kind;
    • check_progress checks only 2 of the 5 Progress sections.
  3. DOC-003 · major: review: approve is self-declared on all 15 Progress pages. No score or reviewer output is stored; the only trace is a free-text "doc-reviewer approve" in the state.json notes, and .autopilot/journal.md holds only its 3-line header.
  4. DOC-004 · major: the W0 Progress pages cite six commits that are not ancestors of HEAD or origin/main. They exist only on origin/claude/foundations-2026-10-26 (and its release-please branch). F1's git log --oneline | tail -3 now prints a5609f5 / 4777f74 / 9185808.
  5. DOC-005 · major: in dark mode the landing shows five light-only screens (four step images and the video poster). Only *_light.webp files exist and shots.py skips dark, yet documentation-system §0.2 and §5 promise pairs.

The sixth major, DOC-006, is the hero video. It autoplays and loops with no controls and no prefers-reduced-motion rule, which fails WCAG 2.2.2. Spec §1 allows only asciinema.js, so a pause control needs a spec change.

Questions for Thomas. These go to TRIAGE1 first. TRIAGE1 then copies the ones it cannot settle to inbox.md. The full wording is in questions for Thomas.

# Ref Question
1 DOC-001 Does documentation-system §2 own the public landing? Retire Landing.dc.html, or keep it as a "post-0.1 marketing draft" without the install line, WES and MCP?
2 DOC-006 Drop autoplay on the hero video (poster plus controls), or allow a small media.js in spec §1 that pauses under reduced motion and adds a pause button?
3 DOC-005 Accept short-term CSS dimming plus a recorded gap in §0.2, or schedule dark board variants now? If now, in which step?
4 DOC-003 Store the doc-reviewer verdict in a journal line or in .autopilot/reviews/<step>.txt? Re-review the 15 existing pages for a stored score, or grandfather them?
5 DOC-004 Is claude/foundations-2026-10-26 the permanent home of the pre-squash SHAs, so pages can link there? Or rewrite the W0 evidence against 9185808?
6 DOC-007, DOC-010 Inbox #1 (Virgil font) is still open. Until then, should the gate accept that PNG figures cannot be regenerated in CI, and should sketch.py fail instead of falling back silently?
7 DOC-013 Hide the GitHub source widget and the footer "Repository" link until the repository is public?

Next. TRIAGE1 sorts these findings with the triage policy. APPLY1 then changes the specs and pages and adds the decision-log entries. The three proposed spikes (spikes/dark-boards/, spikes/docs-gate-coverage/, spikes/landing-render-check/) are not pipeline steps yet; triage decides.