Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

refactor(prompts): tighten the visual-review rubric and stage

hugohe3ca35b95397bd
diff --git a/skills/ppt-master/references/visual-review.md b/skills/ppt-master/references/visual-review.md
index 450d1f7f..ddd6c7cf 100644
--- a/skills/ppt-master/references/visual-review.md
+++ b/skills/ppt-master/references/visual-review.md
@@ -1,251 +1,121 @@
# Visual Review Rubric
-> Per-page visual self-check rubric for slide SVGs. Read by the subagents spawned during the `visual-review` stage. Companion to the [`visual-review` stage](../workflows/stages/visual-review.md) and the [`visual_review.py`](../scripts/visual_review.py) renderer.
+> Per-page visual self-check rubric for slide SVGs, read by the subagents spawned during the [`visual-review` stage](../workflows/stages/visual-review.md). The renderer contract lives in [`svg-pipeline.md`](../scripts/docs/svg-pipeline.md#visual_reviewpy).
## §0 Prerequisites
-This rubric **does not repeat** what `svg_quality_checker.py` already covers. Required upstream order:
-
-```
-Executor finishes page → svg_quality_checker.py passes → visual_review.py renders PNG → this rubric runs
-```
-
-If the static checker has not been run or has failed, the subagent must abort with status `prereq_failed` and not start the rubric. Topics already enforced by the static checker (do **not** re-check here):
-
-- font-size anchor drift (more than `2px` from every declared role anchor)
-- id uniqueness, XML well-formed
-- canvas/structural typography validation and informational spec-lock anchor comparison (contextual colors/fonts are allowed)
-- animation_config compliance
+Required order: Executor finishes page → `svg_quality_checker.py` passes → `visual_review.py` renders PNG → this rubric runs. If the static checker has not run or failed, abort with status `prereq_failed`. Do not re-check what it already enforces: font-size anchor drift (`2px` from every declared role anchor), id uniqueness and XML well-formedness, canvas/structural typography and informational spec-lock comparison, `animation_config` compliance.
## §0.1 Subagent inputs
-Each review subagent processes a **batch** of pages (see §6.1 for batch sizing). The inputs are:
-
-1. **Page batch** — a list of `(svg_path, png_path, page_role, canvas)` records, one per assigned page. `svg_path` resolves under `<project>/svg_output/<page>.svg`, `png_path` under `<project>/.preview/<page>.png`. `page_role` is one of `cover` / `chapter` / `tldr` / `content` / `data` / `closing` / `breathing`, parsed from `design_spec.md §IX` by the orchestrator — subagents do **not** guess. `canvas` is copied verbatim from that page's successful renderer record and contains the root-SVG `view_box`, exact `width` / `height`, and raster `png_width` / `png_height`; subagents never assume a fixed canvas or recompute it from the PNG.
-2. **Path to this rubric file**
-3. **`<project>/design_spec.md`** (read-only) — §IX outline is the source of truth for "what should this page deliver"
-4. **`<project>/spec_lock.md`** (read-only) — brand-locked values
-5. **Style Review Focus excerpt** (conditional, read-only) — supplied by the orchestrator only when an installed `<project>/templates/design_spec.style.<id>.md` exists; it retains the source path and exact §VII wording
-6. **`<project>/.review/`** (writable) — where backups and findings JSON go
+Each subagent processes a batch of pages (§6.1) with these inputs: (1) the page batch — `(svg_path, png_path, page_role, canvas)` records, `svg_path` under `<project>/svg_output/`, `png_path` under `<project>/.preview/`, `page_role` one of `cover` / `chapter` / `tldr` / `content` / `data` / `closing` / `breathing` parsed from `design_spec.md §IX` by the orchestrator (never guessed), `canvas` copied verbatim from the renderer record (`view_box`, `width` / `height`, `png_width` / `png_height`; never assumed or recomputed); (2) this rubric's path; (3) `<project>/design_spec.md` read-only — §IX is the truth for what the page should deliver; (4) `<project>/spec_lock.md` read-only; (5) a Style Review Focus excerpt, only when an installed `templates/design_spec.style.<id>.md` exists, with its source path and exact §VII wording; (6) writable `<project>/.review/`.
-The subagent reads inputs 2–5 **once** at the start of its turn (input 5 may be absent), then iterates over the page batch sequentially (one page at a time): apply the rubric → apply any Style supplement → write `<project>/.review/<page>.json` → move on. This is the core token-saving move — fixed context is read N/K times instead of N times.
-
-Style Review Focus is supplemental acceptance context, not a second rubric. It cannot create new Hard rules, weaken §§1–3, or authorize content, identity, or structural edits. Record a clearly unmet focus item as `rule: "STYLE"`: apply a fix only when the existing rubric already permits that atomic edit; otherwise add a `needs_human_items` entry with a concise suggested fix.
+Read inputs 2–5 once at the start, then iterate the batch sequentially: apply the rubric → apply any Style supplement → write `<project>/.review/<page>.json` → next page. Style Review Focus is supplemental acceptance context, not a second rubric: it cannot add Hard rules, weaken §§1–3, or authorize content, identity, or structural edits. Record a clearly unmet focus item as `rule: "STYLE"`; fix it only when the rubric already permits that atomic edit, otherwise add a `needs_human_items` entry with a suggested fix.
## §1 Hard rules (fix every hit)
| # | Category | Trigger | Permitted fix |
|---|----------|---------|---------------|
-| H1 | Out-of-bounds | element bbox falls outside the bounds declared by `canvas.view_box` | shrink or reposition into canvas |
+| H1 | Out-of-bounds | element bbox outside `canvas.view_box` | shrink or reposition into canvas |
| H2 | Text overflow | text bbox extends past its visual container | reduce font-size or line-break |
-| H3 | Text overlap | two `<text>` elements' bboxes intersect (tspans within one text excluded) | reposition or resize |
-| H4 | Readability | contrast < 4.5 (small text) / < 3.0 (font-size ≥ 24px); OR text directly atop a complex image with no scrim | if **neither** the foreground nor the background color is a brand token: position-only escape — add a `<rect>` scrim under the text, or raise the offending text's font-size to ≥ 24px so the 3.0 threshold applies. If **either** color is a brand token: do not edit the SVG → goto §1.1 escalation. |
-| ~~H5~~ | Font-ramp drift | *covered by `svg_quality_checker.py` — see §0 prerequisites* | n/a (do not re-check) |
+| H3 | Text overlap | two `<text>` bboxes intersect (tspans within one text excluded) | reposition or resize |
+| H4 | Readability | contrast < 4.5 (small text) / < 3.0 (font-size ≥ 24px), or text directly atop a complex image with no scrim | when neither color is a brand token: position-only escape — add a `<rect>` scrim under the text, or raise the text to ≥ 24px so the 3.0 threshold applies; when either color is a brand token: do not edit → §1.1 |
+| ~~H5~~ | Font-ramp drift | covered by `svg_quality_checker.py` (§0) | n/a |
| H6 | Element collision | rect/circle/path bboxes overlap with z-order violating semantics | open spacing |
-| H7 | Declared page chrome displaced | page number / header / footer is explicitly declared by `design_spec §IX`, `spec_lock.md`, or the installed template with a concrete anchor, but is covered, missing, or outside `canvas.view_box` | restore only that declared chrome to its declared anchor; never invent undeclared chrome |
-| H8 | Image rendering broken | `<image>` empty / broken-image / severe distortion | fix `href`; for `adaptive`, choose `meet` or a safer crop; a new complete-display requirement returns to §VIII `Crop Policy` and lock projection |
-| H9 | Missing key element | element required by `design_spec §IX` outline is absent from rendered slide | recreate from spec |
-
-Detection order (run sequentially, do not parallelize within a single subagent):
+| H7 | Declared page chrome displaced | page number / header / footer explicitly declared by `design_spec §IX`, `spec_lock.md`, or the installed template with a concrete anchor is covered, missing, or outside `canvas.view_box` | restore only that declared chrome; never invent undeclared chrome |
+| H8 | Image rendering broken | `<image>` empty / broken / severely distorted | fix `href`; for `adaptive`, choose `meet` or a safer crop; a new complete-display requirement returns to §VIII `Crop Policy` and lock projection |
+| H9 | Missing key element | element required by `design_spec §IX` absent from the render | recreate from spec |
-```
-H1 → H2 → H7 (structure)
-H3 → H6 (collisions)
-H4 (readability)
-H8 → H9 (content)
-```
+Detection order, sequential within one subagent: H1 → H2 → H7 (structure), H3 → H6 (collisions), H4 (readability), H8 → H9 (content).
### §1.1 Brand-token contrast escalation
-If H4 fires and the foreground or background color is a **brand token** (defined in `spec_lock.md`) — i.e., the violation will repeat on every page using that token — do **not** touch the SVG. Brand decisions are §3 Don't-Touch; even position-only escapes (scrim insertion, font-size escalation) shift the page's visual weight in ways that should be a brand-level decision, not a per-page subagent decision. Instead:
-
-1. Record the finding in the page JSON under `needs_human_items` with `rule: "H4"`, the offending element selector, and `suggested_fix_summary` describing the brand-level options (e.g., "raise body-text token from `#6E7681` to `#8B949E` deck-wide" or "introduce a scrim style in the brand").
-2. Append the finding to `<project>/.review/brand_review.json` (append-only log; one entry per distinct token+context pair). The orchestrator aggregates and surfaces this to the main agent at the end of the run so the user can make one cross-deck decision instead of N per-page ones.
-3. The page's `status` is `needs_human` if H4 is the only Hard hit on the page; if other (non-brand) Hard hits were fixed, the page still finishes as `fixed` and the brand-token H4 entry sits in `needs_human_items` alongside.
-
-The aggregated brand review is the responsibility of the orchestrator at the end of the run, not the per-page subagent.
+If H4 fires and the foreground or background is a brand token from `spec_lock.md`, the violation repeats on every page using that token, so do not touch the SVG — even a scrim or size escalation is a brand-level decision. Record the finding under `needs_human_items` with `rule: "H4"`, the element selector, and a `suggested_fix_summary` naming brand-level options (e.g. "raise body-text token from `#6E7681` to `#8B949E` deck-wide"), and append it to `<project>/.review/brand_review.json` (append-only, one entry per distinct token+context pair). The page's `status` is `needs_human` when H4 is its only Hard hit; otherwise it finishes `fixed` with the H4 entry alongside. The orchestrator aggregates brand findings at the end of the run.
## §2 Soft rules (act only when clearly bad)
-Subagents must apply the **clearly bad** threshold — when in doubt, leave it. Better to under-fix than to oscillate.
+When in doubt, leave it — under-fixing beats oscillation.
| # | Category | Trigger | Fix direction |
|---|----------|---------|---------------|
-| S1 | Vertical rhythm tight | Within the **same logical text block**, consecutive baselines have gap < 1.05× larger font-size | open to 1.15–1.3× |
-| S2 | Vertical rhythm hollow | Within one logical block, > 150 px non-decorative whitespace; `breathing` pages exempt | tighten |
-| S3 | Intended anchor missed | hero/title block is clearly displaced from a concrete anchor explicitly declared by `design_spec §IX`, `spec_lock.md`, or the installed template. Canvas center counts only when the plan explicitly calls for centered placement; intentional asymmetry, negative space, and image-focal placement are exempt. | restore toward the declared anchor |
-| S4 | Alignment drift | same-column elements differ in `x` by > 4 px (or same-row baselines by > 4 px) **and** are semantically meant to be on the same grid line | snap to grid |
+| S1 | Vertical rhythm tight | within one logical text block, consecutive baselines gap < 1.05× the larger font-size | open to 1.15–1.3× |
+| S2 | Vertical rhythm hollow | within one block, > 150 px non-decorative whitespace; `breathing` pages exempt | tighten |
+| S3 | Intended anchor missed | hero/title block clearly displaced from a concrete anchor explicitly declared by §IX, the lock, or the template; canvas center counts only when the plan calls for centering — intentional asymmetry, negative space, and image-focal placement are exempt | restore toward the declared anchor |
+| S4 | Alignment drift | same-column `x` or same-row baselines differ by > 4 px and are meant to share a grid line | snap to grid |
| S5 | Grid non-uniform | N-card row: neighbor `x`-spacing differs by > 5% of the average | re-distribute |
-| S6 | CJK letter-spacing | CJK characters with `letter-spacing / font-size > 5%` | reduce to ≤ 2% |
-| S7 | Decorative accents compete | multiple unlocked colors with no semantic role visibly compete with one another and with the intended primary emphasis. Brand colors, natural-media colors, data-series/category colors, status encoding, and other semantic colors are exempt. | consolidate only the competing decorative colors into existing page/deck accents; never recolor locked or semantic elements |
-| S8 | Emphasis mismatch | most visually prominent element ≠ the element `design_spec §IX` declares as the page's primary | rescale to match intent |
-| S9 | Image-text relationship | caption > 60 px from its image; text on busy image without scrim; image clearly purposeless | tighten / add scrim / remove |
-| S10 | Breathing violation | only when `page_role = breathing`: ≥3 rounded card grid | replace with naked text / single hero |
+| S6 | CJK letter-spacing | CJK `letter-spacing / font-size > 5%` | reduce to ≤ 2% |
+| S7 | Decorative accents compete | several unlocked colors with no semantic role visibly compete with each other and the intended primary emphasis; brand, natural-media, data-series, status, and other semantic colors are exempt | consolidate only the competing decorative colors into existing accents; never recolor locked or semantic elements |
+| S8 | Emphasis mismatch | most prominent element ≠ the element §IX declares as the page's primary | rescale to match intent |
+| S9 | Image-text relationship | caption > 60 px from its image; text on a busy image without scrim; image clearly purposeless | tighten / add scrim / remove |
+| S10 | Breathing violation | `page_role = breathing` with a ≥ 3 rounded-card grid | replace with naked text / single hero |
## §3 Don't-touch
-Hard boundary, equal weight to §1.
-
-- **Brand decisions** — color tokens, font families, geometry style (decided by `spec_lock.md` / brand directory)
-- **Layout restructure** — do not change column counts, replace chart types, add/remove sections
-- **Content** — do not add or remove copy; only adjust position, font-size (within the mapped role's anchor `±2px`), spacing, letter-spacing, alignment, scrim
-- **Other files** — never edit `design_spec.md` / `spec_lock.md` / `animations.json` / `image_prompts.json` / `images/` / other pages' SVGs
-- **Atomicity** — one edit per fix, no bulk multi-element replacements
-
-If a "violation" requires reinterpreting `design_spec.md` to fix → mark `needs_human` with a one-line `suggested_fix_summary`.
+Equal weight to §1: brand decisions (color tokens, font families, geometry style from `spec_lock.md` / brand directory); layout restructure (column counts, chart types, sections); content (no added or removed copy — only position, font-size within the role anchor `±2px`, spacing, letter-spacing, alignment, scrim); other files (`design_spec.md`, `spec_lock.md`, `animations.json`, `image_prompts.json`, `images/`, other pages' SVGs); atomicity (one edit per fix, no bulk multi-element replacement). A "violation" that requires reinterpreting `design_spec.md` → `needs_human` with a one-line `suggested_fix_summary`.
## §4 Iteration protocol
### §4.0 Iteration 0 — PNG sanity check
-Run before applying any rule:
-
-- PNG file exists and is non-zero bytes
-- PNG dimensions = that page record's `canvas.png_width` × `canvas.png_height`
-- PNG is **not** all-background (a histogram check: count of background-color pixels < 99% of total) — guards against blank/white-out renders only, **does not** filter sparse dark layouts
-
-Any check fails → status = `render_failed`, abort without scanning rules.
+Before any rule: the PNG exists and is non-empty; its dimensions equal the record's `canvas.png_width` × `canvas.png_height`; it is not all-background (background-color pixels < 99% — guards blank renders only, not sparse dark layouts). Any failure → `render_failed`, abort.
### §4.1 Iteration loop
-The full loop is defined here but the **default budget is 1 iteration**. Multi-iteration runs require an explicit opt-in in the orchestrator prompt and roughly double render cost per added iteration.
-
-```
-iteration 1: scan all Hard + Soft → fix → (re-render only if budget ≥ 2)
-iteration 2 (opt-in): re-verify changed elements + scan for new Hard hits → fix → re-render
-iteration 3 (opt-in): report only, no further fix
-```
-
-Per-iteration fix caps:
-
-- **Hard rules**: no per-round cap — every Hard hit must be addressed in the iteration it was found in
-- **Soft rules**: ≤ 2 fixes per iteration; remaining Soft hits go to `untouched_concerns`
+Default budget is **1 iteration**; more requires explicit opt-in in the orchestrator prompt and roughly doubles render cost per iteration. Iteration 1: scan all Hard + Soft → fix → re-render only if budget ≥ 2. Iteration 2 (opt-in): re-verify changed elements + scan for new Hard hits → fix → re-render. Iteration 3 (opt-in): report only. Hard rules have no per-round cap; Soft rules ≤ 2 fixes per iteration, remainder to `untouched_concerns`.
### §4.2 Termination conditions
-- **Rollback trigger**: any iteration's fix introduces a **new Hard hit** that did not exist before → immediately `cp` the backup back over the SVG, status = `needs_human`, finding records "rolled back fix X — created Hard Y"
-- **Soft thrash trigger** (iteration budget ≥ 2 only): iteration 2's fix introduces a **new Soft hit** that did not exist before → stop, status = `needs_human` with note "fixes are competing"
-- **Clean exit**: iteration ends with zero Hard hits and ≤ 1 Soft hit remaining → status = `ok` if no fixes were applied, `fixed` if any were applied
+Rollback: a fix introduces a new Hard hit → `cp` the backup back, status `needs_human`, record "rolled back fix X — created Hard Y". Soft thrash (budget ≥ 2): iteration 2 introduces a new Soft hit → stop, `needs_human`, "fixes are competing". Clean exit: zero Hard hits and ≤ 1 Soft hit remaining → `ok` if nothing was applied, `fixed` otherwise.
### §4.3 Backup discipline
-Before the **first** `Edit` on a page in any iteration `N`, the subagent must:
-
-```bash
-cp <project>/svg_output/<page>.svg <project>/.review/backup/<page>.iter<N>.svg
-```
-
-The backup path is recorded in every finding's `backup_path` field. Backups are the rollback anchor for §4.2.
+Before the first edit on a page in iteration `N`: `cp <project>/svg_output/<page>.svg <project>/.review/backup/<page>.iter<N>.svg`; record the path in every finding's `backup_path`.
## §5 Output schema
-Each subagent writes exactly one file to `<project>/.review/<page>.json`:
+One file per page at `<project>/.review/<page>.json`; every `needs_human_items` entry carries a `suggested_fix_summary`, never a bare problem description.
```json
{
"page": "02_three_steps.svg",
"page_role": "content",
- "canvas": {
- "view_box": [0, 0, 1242, 1660],
- "width": 1242,
- "height": 1660,
- "png_width": 1242,
- "png_height": 1660
- },
+ "canvas": {"view_box": [0, 0, 1242, 1660], "width": 1242, "height": 1660, "png_width": 1242, "png_height": 1660},
"status": "ok" | "fixed" | "needs_human" | "render_failed" | "prereq_failed",
"iterations_run": 1,
- "screenshot_paths": [
- ".preview/02_three_steps.png",
- ".preview/02_three_steps.iter1.png"
- ],
- "findings": [
- {
- "iter": 1,
- "rule": "S6",
- "severity": "soft",
- "evidence": "letter-spacing=10 on font-size=84, ratio=11.9% > 5%",
- "fix_applied": {
- "element": "#hero-statement text[font-size='84']",
- "before": "letter-spacing=\"10\"",
- "after": "letter-spacing=\"2\""
- },
- "verified_in_iter": 2,
- "backup_path": ".review/backup/02_three_steps.iter1.svg"
- }
- ],
- "untouched_concerns": [
- {
- "rule": "S1",
- "evidence": "...",
- "reason": "soft-cap reached" | "ambiguous_design_intent"
- }
- ],
- "needs_human_items": [
- {
- "rule": "H9",
- "suggested_fix_summary": "Hero subtitle declared in spec §IX.4 missing; add a <text> at (80,496) per design language"
- }
- ],
- "design_intent_check": {
- "spec_says": "TL;DR — emphasize 意图 as the core abstraction",
- "render_delivers": true,
- "note": "..."
- }
+ "screenshot_paths": [".preview/02_three_steps.png", ".preview/02_three_steps.iter1.png"],
+ "findings": [{
+ "iter": 1, "rule": "S6", "severity": "soft",
+ "evidence": "letter-spacing=10 on font-size=84, ratio=11.9% > 5%",
+ "fix_applied": {"element": "#hero-statement text[font-size='84']", "before": "letter-spacing=\"10\"", "after": "letter-spacing=\"2\""},
+ "verified_in_iter": 2,
+ "backup_path": ".review/backup/02_three_steps.iter1.svg"
+ }],
+ "untouched_concerns": [{"rule": "S1", "evidence": "...", "reason": "soft-cap reached" | "ambiguous_design_intent"}],
+ "needs_human_items": [{"rule": "H9", "suggested_fix_summary": "Hero subtitle declared in spec §IX.4 missing; add a <text> at (80,496) per design language"}],
+ "design_intent_check": {"spec_says": "TL;DR — emphasize 意图 as the core abstraction", "render_delivers": true, "note": "..."}
}
```
-`needs_human_items` must include a `suggested_fix_summary` for every entry — never bare problem descriptions.
-
## §6 Dispatch & messaging contract
-This rubric is consumed by subagents spawned via the `visual-review` stage. Mandatory dispatch invariants:
-
### §6.1 Orchestrator → subagent (batched dispatch)
-The orchestrator partitions the N pages into `ceil(N/K)` batches of ≤ K pages each (default **K = 5**; configurable per run via the orchestrator prompt) and spawns one subagent per batch.
-
-- Spawn all batch subagents in **one assistant message** (parallel `Agent` calls). Sequential dispatch breaks pipelining.
-- Each subagent prompt is **self-contained** — no prior conversation context. Inline the absolute paths for §0.1 inputs 1–5 explicitly, plus the full `(svg_path, png_path, page_role, canvas)` records for that batch. Do not assume the subagent knows the project root.
-- `subagent_type: general-purpose`. Tool restrictions: Read, Edit, Bash (for `cp` backups), Write (for JSON output). MCP playwright is **not** required by subagents — orchestrator pre-renders PNGs.
-- `name` / `team_name` parameters may be unavailable from nested teammate context. Dispatch must remain functional with anonymous subagents — do not require named addressing.
-
-**Why batched, not per-page**: the rubric (~2.5K tokens), `design_spec.md` (~4–5K), and `spec_lock.md` (~1K) are identical inputs across all pages and do **not** share a prompt cache between sibling subagents. A 20-page deck with per-page dispatch re-reads ~150K tokens of fixed documents; batched dispatch with K=5 cuts that by ~75% while staying inside default parallel-subagent limits (~10). Batches also bound failure blast radius — one crashed subagent loses K pages, not the entire run.
+The orchestrator partitions N pages into `ceil(N/K)` batches of ≤ K pages (default **K = 5**, configurable per run) and spawns one subagent per batch, all in one assistant message (parallel `Agent` calls). Each prompt is self-contained — absolute paths for inputs 1–5 plus the full batch records; no prior context assumed. `subagent_type: general-purpose`; tools Read, Edit, Bash (`cp` backups), Write (JSON); no playwright — the orchestrator pre-renders. Dispatch must work with anonymous subagents when `name` / `team_name` are unavailable.
-**Batch size guidance**:
-- `K = 5` (default) — balanced; safe for decks up to ~50 pages
-- `K = 3` — high-fidelity / small decks (≤ 12 pages); slightly higher parallelism
-- `K = 10` — token-sensitive / large decks (50+ pages); fewer subagents, larger blast radius per failure
-
-Larger K is **not** always better: subagent context fills with prior pages' SVG / PNG / findings as the batch progresses, and beyond ~10 pages context auto-compression starts dropping early findings. Keep K such that `K × (avg_svg_size + image_token_cost + report_size)` stays well under the subagent context budget.
+Batched dispatch exists because the rubric (~2.5K tokens), `design_spec.md` (~4–5K), and `spec_lock.md` (~1K) are identical across pages and do not share a prompt cache between siblings: K=5 cuts fixed-document re-reads by ~75% on a 20-page deck and bounds failure blast radius. Guidance: K=5 default (decks to ~50 pages), K=3 for high-fidelity short decks, K=10 for token-sensitive large decks; beyond ~10 pages subagent context compression starts dropping early findings, so keep `K × (avg_svg_size + image_token_cost + report_size)` well under the subagent budget.
### §6.2 Subagent → orchestrator
-- Subagent's **final action before going idle** must be `SendMessage(to=<lead>)` listing one JSON path per processed page (e.g., `<project>/.review/<page>.json`) and a ≤150-word text summary covering all pages in the batch. Going idle without messaging — or messaging with a partial batch — is a protocol violation.
-- If the subagent aborts mid-batch (rule §4.2 rollback, tool error, etc.), it must still send the batch report covering both completed and aborted pages, with the aborted pages marked `needs_human` or `render_failed` as appropriate.
+The subagent's final action before idling is `SendMessage(to=<lead>)` listing one JSON path per processed page and a ≤150-word summary of the batch; idling without messaging or with a partial batch is a violation. A mid-batch abort still sends the report with aborted pages marked `needs_human` or `render_failed`.
### §6.3 Orchestrator → main agent
-- Orchestrator's **final action before going idle** must be `SendMessage(to=<lead>)` containing:
- - the aggregate Markdown table (page × status × hard_hits × soft_hits × fixes_applied × needs_human_reason)
- - one ≤150-word "plumbing verdict" paragraph
- - path to `brand_review.json` if any §1.1 aggregations occurred
+The orchestrator's final action is `SendMessage(to=<lead>)` with the aggregate table (page × status × hard_hits × soft_hits × fixes_applied × needs_human_reason), one ≤150-word plumbing verdict, and the `brand_review.json` path if any §1.1 aggregation occurred.
### §6.4 Concurrency
-- Pre-rendering is serialized by `visual_review.py`'s file lock at `<project>/.preview/.render.lock`. Subagents must **not** call the renderer concurrently. Re-renders during iteration loop go through the same lock.
-
-## §7 Renderer expectations *(script contract)*
-
-`visual_review.py <project> [pages...]` must guarantee:
+Rendering is serialized by `visual_review.py`'s lock at `<project>/.preview/.render.lock`; subagents never call the renderer concurrently, and iteration re-renders go through the same lock.
-- Output PNG matches what the user would see in the live-preview browser (inlined `<use data-icon>`, resolved `<image href>`)
-- The root SVG `viewBox` is the canvas source of truth; each successful page record includes its exact `view_box`, `width` / `height`, and raster `png_width` / `png_height`
-- Output dimensions = that page record's `png_width` × `png_height`
-- File-lock serialization at `<project>/.preview/.render.lock`
-- Clean exit codes:
- - `0` — all requested pages rendered
- - `2` — live-preview server not running for this project (subagent should not retry; surfaces to the orchestrator)
- - `3` — rendering backend (playwright + chromium) missing or unable to launch (config error, surface to user)
- - `4` — page-level render failure (specific failures listed in stderr; partial output is acceptable)
+## §7 Renderer expectations
-The renderer never edits SVGs and never reads any rule from this rubric — it is a pure render-and-validate tool.
+`visual_review.py` is a pure render-and-validate tool: it never edits SVGs and reads no rule from this rubric. Its output, canvas, lock, and exit-code contract is documented in [`svg-pipeline.md`](../scripts/docs/svg-pipeline.md#visual_reviewpy).
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 5f5357d4..aad8d13c 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -973,6 +973,19 @@ Behind [`native-formula.md`](../../references/native-formula.md) §3. The compil
**Compatibility**: the package uses standard editable Office Math and keeps the PowerPoint 2010+ target; the executable profile is pinned to the documentation versions above. Repository verification covers compilation, OMML structure, and PPTX packaging, not a Microsoft 365 UI rendering/editability certification. Earlier PowerPoint versions are not the source-profile baseline; WPS, Keynote, LibreOffice, and other clients receive no embedded fallback. Reverse import is described in [`conversion.md`](conversion.md#native-formula-reverse-import).
+## `visual_review.py`
+
+Pure render-and-validate tool for the [`visual-review`](../../workflows/stages/visual-review.md) stage; it never edits SVGs and reads no rubric rule.
+
+```bash
+python3 scripts/visual_review.py <project_path> [--pages <token> ...] [--server-url http://127.0.0.1:<P>]
+```
+
+- Requires `playwright` plus chromium and a running live-preview server for the same project; without `--server-url` it discovers the port from `<project>/live_preview/lock.json`, and in either case validates `/api/health` against the target project and rejects a server for another project.
+- Output PNG matches the live-preview browser (inlined `<use data-icon>`, resolved `<image href>`); the root SVG `viewBox` is the canvas source of truth, and each successful page record carries `view_box`, `width` / `height`, and raster `png_width` / `png_height`; output dimensions equal that record's raster size. A record with `"all_background": true` rendered to a blank surface.
+- Renders are serialized by `<project>/.preview/.render.lock`, so concurrent invocation is safe.
+- Exit codes: `0` all requested pages rendered; `2` live-preview server unreachable or serving a different project; `3` playwright/chromium missing or unable to launch; `4` page-level render failure (details on stderr, partial output on disk).
+
## `total_md_split.py`
Split `total.md` into per-slide note files.
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 24edb6d0..acd23b61 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -58,7 +58,9 @@
"skills/ppt-master/workflows/stages/verify-charts.md": 2500,
"skills/ppt-master/workflows/stages/topic-research.md": 2000,
"skills/ppt-master/workflows/stages/live-preview.md": 1000,
- "skills/ppt-master/workflows/stages/web-image-review.md": 750
+ "skills/ppt-master/workflows/stages/web-image-review.md": 750,
+ "skills/ppt-master/references/visual-review.md": 3500,
+ "skills/ppt-master/workflows/stages/visual-review.md": 1750
},
"load_sets": {
"bootstrap.routing": {
diff --git a/skills/ppt-master/workflows/stages/visual-review.md b/skills/ppt-master/workflows/stages/visual-review.md
index 6ccac964..8b4f96bb 100644
--- a/skills/ppt-master/workflows/stages/visual-review.md
+++ b/skills/ppt-master/workflows/stages/visual-review.md
@@ -4,51 +4,24 @@ description: Optional quality-gate stage for per-page rubric-based visual review
# Visual Review Stage
-> Optional Generate-PPTX quality stage. Goal: reduce human iteration by letting AI subagents visually self-check each rendered slide against a fixed rubric and apply atomic position/spacing fixes.
->
-> Reads `<project>/svg_output/<page>.svg` and a pre-rendered PNG of each slide, then either applies a fix or flags `needs_human`. When an installed Style exists, it also reads that workspace's `Review Focus` as supplemental acceptance context. **Never touches** brand decisions, layout structure, or other files.
->
-> This stage is **context-independent** — invokable in a fresh chat session with only `<project_path>` as input. No upstream conversation context required.
-
-## Positioning
-
-This is an **optional auxiliary loop**, opt-in only. The [`generate-pptx`](../generate-pptx.md) Step 1–7 pipeline does not invoke it; trigger only when the user explicitly asks for a visual re-pass on the generated SVGs before export.
-
-**Token cost**: each batch subagent re-reads the rubric + `design_spec.md` + `spec_lock.md` + the short Style Review Focus when present, and processes K SVG+PNG pairs. For a 20-page deck with K=5, expect on the order of 100–150K additional input tokens on top of the main generation run.
+> Optional, opt-in Generate-PPTX quality stage: AI subagents visually self-check each rendered slide against the fixed rubric in [`references/visual-review.md`](../../references/visual-review.md) and apply atomic position/spacing fixes or flag `needs_human`. When an installed Style exists, its `Review Focus` is supplemental acceptance context. Never touches brand decisions, layout structure, or other files. Context-independent — invokable in a fresh chat with only `<project_path>`.
## When to Run
-- Executor ([`generate-pptx`](../generate-pptx.md) Step 6) has finished all pages
-- `svg_quality_checker.py` has passed
-- Post-processing (`finalize_svg.py`, `svg_to_pptx.py`) has **not** yet run
-- The user has explicitly requested visual review
+Only when the user explicitly requests visual review — never auto-invoked from model capability or deck size — after Executor has finished all pages and `svg_quality_checker.py` has passed, before `finalize_svg.py` / `svg_to_pptx.py`. Run [`verify-charts`](./verify-charts.md) first for decks with data charts; this stage covers rhythm, collision, and alignment, not coordinate math. Do not run when `svg_output/` is incomplete, the static checker has not passed, or the user is already in a `live-preview` annotation loop.
-For decks containing data charts, run [`verify-charts`](./verify-charts.md) first — visual-review focuses on visual rhythm / collision / alignment, not chart coordinate math.
-
-## When NOT to Run
-
-- The project has no `svg_output/<page>.svg` files yet — finish Executor first
-- `svg_quality_checker.py` has not been run or has failed — fix static violations first
-- User has already applied annotations via the `live-preview` stage and is in a fixed-edit loop — describe changes directly, do not re-trigger rubric
-- The user has not asked for it — do not auto-invoke based on inferred model capability or deck size
+**Token cost**: each batch subagent re-reads the rubric + `design_spec.md` + `spec_lock.md` (+ Style Review Focus) and processes K SVG+PNG pairs — on the order of 100–150K additional input tokens for a 20-page deck at K=5.
---
## Prerequisites
```bash
-# 1. playwright + chromium installed (the PNG renderer)
-pip install playwright
-python3 -m playwright install chromium
-
-# 2. live-preview server running for this project (provides inlined SVG fetch)
-python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --no-browser
-# (single instance per project — if it's already running, skip)
+pip install playwright && python3 -m playwright install chromium # PNG renderer
+python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --no-browser # live-preview server (skip if already running)
```
-The renderer (`visual_review.py`) does **not** auto-start the live-preview server. Without `--server-url`, it discovers the actual port from the target project's `live_preview/lock.json`; an explicit `--server-url` overrides discovery. In either case it validates `/api/health` against the resolved target project before rendering and rejects a server for another project.
-
-> **Why playwright, not cairosvg**: cairo's text API has no font-fallback chain, so CJK characters render as tofu boxes for any deck whose font-family list relies on system fallback (Microsoft YaHei / PingFang SC / etc.). Playwright drives a real chromium and produces output identical to what the live-preview browser shows — the only fidelity-preserving option for bilingual decks.
+The renderer does not auto-start the server; it discovers the port from `live_preview/lock.json` (or an explicit `--server-url`) and validates `/api/health` against the target project. Playwright, not cairosvg, because cairo has no font-fallback chain and renders CJK as tofu; chromium output matches the live-preview browser.
---
@@ -58,121 +31,48 @@ The renderer (`visual_review.py`) does **not** auto-start the live-preview serve
python3 skills/ppt-master/scripts/visual_review.py <project_path>
```
-This writes one PNG per page to `<project_path>/.preview/<page>.png`, sized from that SVG root's `viewBox`, with `<use data-icon>` inlined and `<image href>` resolved exactly as the live-preview browser sees them. Each successful page record in the JSON summary includes the exact canvas plus its raster dimensions. Renders are serialized via a project-local file lock — safe to invoke concurrently.
-
-Exit codes:
-
-- `0` — all pages rendered
-- `2` — live-preview server unreachable or serving a different project (start the target project's server per Prerequisites)
-- `3` — playwright python / chromium not installed (or browser failed to launch)
-- `4` — one or more page-level render failures (see stderr; partial output is on disk)
+Writes one PNG per page to `<project_path>/.preview/<page>.png`, sized from the root `viewBox` with icons inlined and images resolved; each successful record carries the exact canvas and raster dimensions (contract and exit codes in [`svg-pipeline.md`](../../scripts/docs/svg-pipeline.md#visual_reviewpy)).
-If any page comes back with `"all_background": true` in the JSON summary, that page rendered to a blank surface — investigate before continuing (broken `<use>` reference, missing image asset, etc.).
-
-**Mandatory — normalize partial renders before dispatch**: parse the renderer
-summary before Step 2. Dispatch only records with `"ok": true`,
-`"all_background": false`, and a complete `canvas` object. For every other page,
-the main agent adds a `render_failed` row directly to the aggregate with the
-renderer error or blank-surface reason; no per-page `.review/<page>.json` is
-expected until that page renders successfully. Exit `2` or `3` stops dispatch
-entirely. Exit `4` may still review the successful subset, but the stage cannot
-finish cleanly until every failed page is retried or handed off per Step 4.
+**Mandatory — normalize partial renders before dispatch**: dispatch only records with `"ok": true`, `"all_background": false`, and a complete `canvas`. For every other page the main agent adds a `render_failed` row to the aggregate with the renderer error or blank-surface reason (a blank surface usually means a broken `<use>` reference or missing image asset). Exit `2` or `3` stops dispatch; exit `4` may review the successful subset, but the stage cannot finish until every failed page is retried or handed off per Step 4.
---
## Step 2 — Spawn the review team
-Create a team and dispatch one orchestrator agent. The orchestrator partitions the N pages into batches of ≤ K pages (default **K = 5**) and spawns one subagent per batch **in parallel** (single message, `ceil(N/K)` parallel `Agent` calls). Each batch subagent reads the fixed inputs (rubric + `design_spec.md` + `spec_lock.md` + conditional Style Review Focus) **once**, then iterates over its assigned pages sequentially.
-
-Before dispatch, look for `<project>/templates/design_spec.style.*.md`. For each one found, read only its `## VII. Review Focus` once and include those checks in every batch prompt. Otherwise pass no Style supplement. This lookup never triggers visual review; it runs only after the user has already activated this stage. The supplement cannot weaken the fixed rubric or widen edit permissions.
+Before dispatch, look for `<project>/templates/design_spec.style.*.md`; for each, read only its `## VII. Review Focus` once and include those checks in every batch prompt — this lookup never triggers the stage and cannot weaken the rubric or widen edit permissions.
```text
TeamCreate(team_name="visual-review-<project>", agent_type="orchestrator")
-Agent(
- team_name="visual-review-<project>",
- subagent_type="general-purpose",
- name="orchestrator",
- prompt=<orchestrator-prompt>,
-)
+Agent(team_name="visual-review-<project>", subagent_type="general-purpose", name="orchestrator", prompt=<orchestrator-prompt>)
```
-The orchestrator prompt must be self-contained and is the **single** place where dispatch shape, batch size, and forbid lists are stated — the rubric (`references/visual-review.md`) defines the contract those prompts must satisfy. Required fields (all absolute paths):
-
-- `<project_path>` — project root
-- Full page list with `page_role` and the successful renderer record's `canvas` per page (parse `<project>/design_spec.md` §IX outline; **fixed compatibility default**: if an existing `design_spec.md` lacks §IX, use `content` for every page and flag this in the final report; if `design_spec.md` itself is missing, restore it through [`failure-recovery.md`](../governance/failure-recovery.md) §3 before dispatch). Pass `canvas` through verbatim; do not assume a fixed slide size.
-- Batch size `K` (default 5; raise to 10 for token-sensitive runs on large decks, lower to 3 for high-fidelity short decks — see rubric §6.1)
-- Iteration budget per page (default 1; 2 only for high-stakes / final-cut runs — see [Appendix: Iteration loop](#appendix-iteration-loop-opt-in))
-- Path to the rubric: `skills/ppt-master/references/visual-review.md`
-- Style Review Focus excerpt, only when the conditional lookup above found one; preserve its wording and source path
-- Dispatch contract reference: rubric [§6](../../references/visual-review.md#6-dispatch--messaging-contract) (batched parallel spawn, self-contained prompts, mandatory `SendMessage` on idle, anonymous-name tolerance)
-- Subagent forbid list: do not edit any other page, `design_spec.md`, `spec_lock.md`, anything under `templates/`, `animations.json`, `image_prompts.json`, or `images/`
+The orchestrator partitions N pages into batches of ≤ K (default 5) and spawns one subagent per batch in parallel; each subagent reads the fixed inputs once, then iterates its pages. The orchestrator prompt is self-contained and the single place stating dispatch shape, batch size, and forbid lists; it carries (absolute paths): `<project_path>`; the full page list with `page_role` and each successful renderer record's `canvas` (parse `design_spec.md` §IX — **fixed compatibility default**: a `design_spec.md` without §IX uses `content` for every page and flags it in the report; a missing `design_spec.md` is restored through [`failure-recovery.md`](../governance/failure-recovery.md) §3 first); batch size K (10 for token-sensitive large decks, 3 for high-fidelity short decks — rubric §6.1); iteration budget (default 1; 2 only for final-cut runs — see the appendix); the rubric path; the Style Review Focus excerpt with its wording and source path when found; the dispatch contract reference (rubric §6); and the subagent forbid list (no edits to other pages, `design_spec.md`, `spec_lock.md`, `templates/`, `animations.json`, `image_prompts.json`, `images/`).
-**Host compatibility**: `TeamCreate` and `SendMessage` are Claude-Code-specific multi-agent primitives. On hosts without those primitives (Cursor, VS Code + Copilot, Codebuddy, etc.) the main agent processes batches sequentially — same partitioning, same per-batch prompts, no parallel dispatch. Token savings from shared fixed inputs still apply; wall-clock time grows roughly N/K-fold.
+**Host compatibility**: `TeamCreate` and `SendMessage` are Claude-Code primitives; on other hosts the main agent processes the same batches sequentially with the same prompts — token savings persist, wall-clock grows roughly N/K-fold.
---
## Step 3 — Aggregate findings
-The orchestrator emits the aggregate Markdown table back to you (the main agent):
-
-```
-| page | role | status | hard_hits | soft_hits | fixes_applied | needs_human_reason |
-|------|------|--------|-----------|-----------|---------------|---------------------|
-```
-
-Statuses:
-
-- `ok` — page passed clean, no fixes applied
-- `fixed` — at least one fix applied, all Hard rules now pass
-- `needs_human` — fix attempted but rolled back (rule §4.2), or rule violation requires brand/structure decision outside the rubric's scope
-- `render_failed` — Iteration 0 PNG sanity failed (rare; usually means renderer / server issue)
-- `prereq_failed` — static checker hadn't been run
-
-Plus a brand-token aggregate at `<project>/.review/brand_review.json` if any §1.1 escalations occurred — review this once at the end of the run, not per page.
+The orchestrator returns `| page | role | status | hard_hits | soft_hits | fixes_applied | needs_human_reason |`, where `ok` = clean, `fixed` = fixes applied and Hard rules pass, `needs_human` = a fix was rolled back (rubric §4.2) or the violation needs a brand/structure decision, `render_failed` = iteration-0 sanity failed, `prereq_failed` = static checker not run — plus `<project>/.review/brand_review.json` when §1.1 escalations occurred, reviewed once at the end.
---
## Step 4 — Decide next move
-For each row in the table:
-
-- `ok` / `fixed` — no action; the SVG has been updated in-place (originals are at `<project>/.review/backup/<page>.iter<N>.svg`)
-- `needs_human` — read the page's JSON `needs_human_items[].suggested_fix_summary`, decide with the user whether to apply or defer
-- `render_failed` — re-run `visual_review.py` for that page only (`--pages <token>`); if it persists, hand off to manual review
-- `prereq_failed` — go back and run `svg_quality_checker.py`
-
-If `brand_review.json` is non-empty, that's a single decision applied across the deck (e.g., bump footer text color from `#6E7681` to `#8B949E` — one change, every page benefits). Do this once, then optionally re-run visual-review for the affected pages only.
-
-After the table is clean, continue to [`generate-pptx`](../generate-pptx.md)
-Step 7. That authority owns the serial commands, gates, and success criteria for
-post-processing and export.
+`ok` / `fixed` — nothing to do; the SVG was updated in place with originals at `<project>/.review/backup/<page>.iter<N>.svg`. `needs_human` — read `needs_human_items[].suggested_fix_summary` and decide with the user. `render_failed` — re-run `visual_review.py --pages <token>`; if it persists, hand off to manual review. `prereq_failed` — run `svg_quality_checker.py`. A non-empty `brand_review.json` is one deck-wide decision (e.g. bump a footer token deck-wide); apply it once, then optionally re-review the affected pages. When the table is clean, continue to [`generate-pptx`](../generate-pptx.md) Step 7.
---
## Notes & invariants
-- **Single source of truth for rules**: [`references/visual-review.md`](../../references/visual-review.md). This stage file is just the orchestration — never restate or paraphrase rules here.
-- **Concurrency**: `visual_review.py` serializes renders via `<project>/.preview/.render.lock`. Subagents must never call the renderer directly without the lock.
-- **Iteration budget**: default 1 iteration. Bumping to 2 doubles render cost and roughly triples token cost. Only worth it for high-stakes / final-cut decks.
-- **Don't-touch (rubric §3)** is hard-enforced by subagents. If you want the subagent to e.g. change a brand color, that is **out of scope** — make the change manually first, then re-render & re-review.
-- **Backups**: every modified SVG has a `.review/backup/<page>.iter<N>.svg` rollback anchor. Restore by `cp`.
-- **The rubric is not the designer**: it catches collisions, drift, and rhythm errors — it does not improve a fundamentally weak layout. If 80%+ of pages come back `needs_human`, the Design Spec's pattern selection or Executor's realization geometry is the root cause, not this stage.
-- **Playwright output discipline**: when an agent uses the playwright MCP tool `browser_take_screenshot` directly (outside the `visual_review.py` script), the `filename` parameter is resolved against the CWD (typically the repo root) — passing a bare relative path will create stray directories inside the repository. Always pass an absolute path:
- - One-off probe / ad-hoc inspection → `/tmp/probe-<topic>-<n>.png`
- - Project artifact (replaces what the script would have produced) → `<project_path>/.preview/<page>.png` (absolute)
- - Never write to `<repo>/<anything>.png` or `<repo>/<some_dir>/...` — those are caught by `.gitignore` patterns but the cleanup burden is real
-
- The `visual_review.py` script handles output paths correctly on its own; this rule only applies to direct playwright MCP usage during interactive exploration or recovery.
+- The rubric is the single source of rules; this file is orchestration only and never restates them.
+- Don't-touch (rubric §3) is hard-enforced: a brand color change is out of scope — make it manually, then re-render and re-review.
+- The rubric catches collisions, drift, and rhythm errors, not a fundamentally weak layout; if 80%+ of pages come back `needs_human`, the root cause is the Design Spec's pattern selection or Executor geometry.
+- Direct playwright MCP `browser_take_screenshot` resolves `filename` against the CWD (usually the repo root): always pass an absolute path — `/tmp/probe-<topic>-<n>.png` for ad-hoc probes, `<project_path>/.preview/<page>.png` for project artifacts; never write under the repository. `visual_review.py` handles its own paths.
---
## Appendix: Iteration loop (opt-in)
-Default behavior is single-iteration review: one scan, fix in place, write the report. The full iteration loop in [`references/visual-review.md`](../../references/visual-review.md) §4.1 supports:
-
-1. Iteration 1: scan + fix
-2. Re-render via `visual_review.py --pages <token>`
-3. Iteration 2: re-verify changed elements + scan for new Hard hits
-4. Rollback on any new Hard hit introduced by a fix
-
-To enable, set iteration budget = 2 in the orchestrator prompt (this is a prompt-level instruction to subagents; neither `visual_review.py` nor the harness enforces it). Each added iteration roughly doubles render cost and triples token cost on the affected pages — reserve for final-cut runs only.
+Default is one iteration. With budget 2 in the orchestrator prompt (a prompt-level instruction; neither the script nor the harness enforces it): iteration 1 scan + fix → re-render via `visual_review.py --pages <token>` → iteration 2 re-verify changed elements and scan for new Hard hits, rolling back any fix that introduced one (rubric §4.1–§4.2). Each added iteration roughly doubles render cost and triples token cost; reserve for final-cut runs.