Two new pieces close the generation→validation→saturation feedback loop:
1. gemini_cli_llm_judge.py — multi-criteria validator. For each draft,
judges math correctness, cell-fit (does it actually target the
declared track/zone/level?), scenario realism, uniqueness vs canonical
questions, and visual-asset alignment. Returns PASS/NEEDS_FIX/DROP
per item. Batched (default 15 per call) for budget efficiency.
2. iterate_coverage_loop.py — drives the full loop:
analyze → plan → generate → render → judge → apply → re-analyze.
Self-paced: stops when (a) top priority gap drops below threshold,
(b) DROP rate exceeds the saturation/hallucination threshold,
(c) total API calls exceed budget, or (d) the same cell is top
priority for two iterations in a row (convergence). The user no
longer specifies "how many questions" — the loop generates until
the corpus reaches a measurable steady state.
Plus 25 round-1 visual questions generated by the new batched generator
(5 batched calls × 5 cells each, zero failures).
The loop is the answer to "we need balance, not just volume": every
iteration's plan derives from a fresh analysis of where coverage is
weakest, so generation can never over-fill an already-saturated cell.
Schema fix: visual.kind is always 'svg' (the format the website ships) and
visual.path points to that asset. The build-pipeline format is recorded as
optional metadata in visual.source_format ('dot' | 'matplotlib' | 'hand'),
which the website ignores. This separates "what users render" from "how
maintainers built it".
Source files live next to the SVG by naming convention; the renderer infers
the path from the YAML's source_format hint without a dedicated source field.
Five new visual exemplars generated by Gemini 3.1 Pro Preview, covering
diverse archetypes:
- cloud-2849 (DOT): incast-bottleneck topology
- cloud-2850 (DOT): leaf-spine fabric with 2:1 oversubscription
- cloud-2851 (matplotlib): bandwidth bar chart for data pipeline diagnosis
- cloud-2852 (matplotlib): checkpoint/recovery timeline with RPO/RTO
- edge-0972 (matplotlib): Poisson vs bursty queueing curves
Plus the four prior exemplars (cloud-2846, 2847, 2848, tinyml-0816)
re-emitted under the new schema. cloud-visual-001 unchanged — already had
the correct shape.
ARCHITECTURE.md rewritten to document the simpler three-layer separation
(website / build / authoring).
ARCHITECTURE.md establishes that visuals are a property of any question, not
a separate category. Three supported formats let the layout engine do the
work: DOT for graph topology, matplotlib for curves and Gantt charts, hand
SVG for custom layouts.
render_visuals.py is the single entry point that dispatches by visual.kind,
runs the appropriate tool, and normalizes the rendered SVG to the book's
font stack. It is idempotent and supports --dry-run.
Three exemplars cover the three formats:
- cloud-2846 (DOT): Tree AllReduce on 8 ranks — auto-laid-out topology
- cloud-2847 (matplotlib): Queueing hockey-stick curve with SLO line
- cloud-2848 (matplotlib): Pipeline-bubble Gantt for GPipe schedule
All three are status:draft pending math review and promotion in a later
batch. Existing cloud-visual-001 remains unchanged as the canonical
hand-SVG exemplar.
Seeds the visuals/ directory with a reference pattern so future
authors have a concrete template to clone.
Exemplar: Ring AllReduce on 4 ranks (cloud track, L3, apply/analyze).
- SVG follows .claude/rules/svg-style.md: 680×460 viewBox, Helvetica
Neue, compute-blue ranks, orthogonal ring arrows, 10-px grid.
- YAML wires the visual block (kind=svg, path=cloud-visual-001.svg,
alt + caption) and pairs it with a matching question: 'Using the
diagram, calculate the total time to complete the full AllReduce.'
- The realistic_solution walks through 2(N−1)/N × data / bw and
explains the common failure mode (forgetting the all-gather phase).
Napkin math shows the step-time decomposition.
AUTHORING.md: the when/how/why guide for future visual questions.
- When a visual earns its place — three criteria (ask requires the
diagram, encodes info text cannot, static suffices).
- High-value candidate topics — ring/tree AllReduce, roofline, KV
cache, pipeline bubbles, memory hierarchy, MCU memory maps,
systolic arrays, attention, MoE.
- Step-by-step authoring workflow pointing at the book's SVG style
guide for the visual system — readers already know the visual
vocabulary from the book, so consistency transfers.
- Accessibility requirements (non-negotiable): alt is enforced by
the Pydantic schema, colour never the sole semantic channel, text
in <text> elements not paths, WCAG AA contrast.
- Explicit anti-patterns: no inline SVG in YAML, no mermaid for
non-graph content, no decorative effects, no label duplication of
scenario prose.
