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.mdindex 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.mdindex 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.jsonindex 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.mdindex 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 servepython3 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.```textTeamCreate(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.