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(visual-review): batch dispatch and tighten workflow positioning

hugohe33c8127747087
diff --git a/skills/ppt-master/references/visual-review.md b/skills/ppt-master/references/visual-review.md
index 8891ca98..270d5b58 100644
--- a/skills/ppt-master/references/visual-review.md
+++ b/skills/ppt-master/references/visual-review.md
@@ -19,15 +19,15 @@ If the static checker has not been run or has failed, the subagent must abort wi
## §0.1 Subagent inputs
-Every per-page review subagent must receive:
+Each review subagent processes a **batch** of pages (see §6.1 for batch sizing). The inputs are:
-1. **SVG path** — the assigned page under `<project>/svg_output/<page>.svg`
-2. **PNG path** — pre-rendered 1280×720 screenshot at `<project>/.preview/<page>.png`
-3. **`page_role`** — one of `cover` / `chapter` / `tldr` / `content` / `data` / `closing` / `breathing`. Parsed from `design_spec.md §IX` by the orchestrator. Subagents do **not** guess.
-4. **Path to this rubric file**
-5. **`<project>/design_spec.md`** (read-only) — §IX outline is the source of truth for "what should this page deliver"
-6. **`<project>/spec_lock.md`** (read-only) — brand-locked values
-7. **`<project>/.review/`** (writable) — where backups and findings JSON go
+1. **Page batch** — a list of `(svg_path, png_path, page_role)` tuples, 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.
+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. **`<project>/.review/`** (writable) — where backups and findings JSON go
+
+The subagent reads inputs 2–4 **once** at the start of its turn, then iterates over the page batch sequentially (one page at a time): apply the rubric → write `<project>/.review/<page>.json` → move on. This is the core token-saving move — three fixed documents are read N/K times instead of N times.
## §1 Hard rules (fix every hit)
@@ -36,14 +36,13 @@ Every per-page review subagent must receive:
| H1 | Out-of-bounds | element bbox falls outside `0,0,1280,720` | 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 | **(v2)** 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. Full color change is brand-locked → goto §1.1 escalation. |
+| H4 | Readability | contrast < 4.5 (small text) / < 3.0 (font-size ≥ 24px); OR text directly atop a complex image with no scrim | 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. Full color change is brand-locked → goto §1.1 escalation. |
+| ~~H5~~ | Font-ramp drift | *covered by `svg_quality_checker.py` — see §0 prerequisites* | n/a (do not re-check) |
| H6 | Element collision | rect/circle/path bboxes overlap with z-order violating semantics | open spacing |
| H7 | Anchored element displaced | page number / header / footer covered, missing, or out of canvas | restore to anchor position |
| H8 | Image rendering broken | `<image>` empty / broken-image / severe distortion | fix `href`, adjust `preserveAspectRatio`, add `no-crop` if face/data is cropped |
| H9 | Missing key element | element required by `design_spec §IX` outline is absent from rendered slide | recreate from spec |
-*H5 (font-ramp drift) is covered by `svg_quality_checker.py` and intentionally omitted.*
-
Detection order (run sequentially, do not parallelize within a single subagent):
```
@@ -53,7 +52,7 @@ H4 (readability)
H8 → H9 (content)
```
-### §1.1 Brand-token contrast escalation *(new in v2)*
+### §1.1 Brand-token contrast escalation
If H4 fires and the underlying color is a **brand token** (defined in `spec_lock.md`) — i.e., the violation will repeat on every page using that token — do **not** mark the page `needs_human`. Instead:
@@ -94,7 +93,7 @@ If a "violation" requires reinterpreting `design_spec.md` to fix → mark `needs
## §4 Iteration protocol
-### §4.0 Iteration 0 — PNG sanity check *(v2 — relaxed)*
+### §4.0 Iteration 0 — PNG sanity check
Run before applying any rule:
@@ -102,14 +101,16 @@ Run before applying any rule:
- PNG dimensions = 1280 × 720
- 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. The earlier "non-bg pixel ratio ≥ 5%" rule is **deprecated** — it false-fires on legitimate minimalist dark decks (verified empirically in v1 plumbing test).
+Any check fails → status = `render_failed`, abort without scanning rules.
### §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 → re-screenshot
-iteration 2: re-verify changed elements + scan for new Hard hits → fix → re-render
-iteration 3: report only, no further fix
+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:
@@ -120,8 +121,8 @@ Per-iteration fix caps:
### §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 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 1 ends with zero Hard hits and ≤ 1 Soft hit remaining → status = `ok` if no fixes were applied, `fixed` if any were applied
+- **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
### §4.3 Backup discipline
@@ -185,20 +186,32 @@ Each subagent writes exactly one file to `<project>/.review/<page>.json`:
`needs_human_items` must include a `suggested_fix_summary` for every entry — never bare problem descriptions.
-## §6 Dispatch & messaging contract *(new in v2)*
+## §6 Dispatch & messaging contract
This rubric is consumed by subagents spawned via the `visual-review` workflow. Mandatory dispatch invariants:
-### §6.1 Orchestrator → subagent
+### §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 per-page 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–7 explicitly. Do not assume the subagent knows the project root.
+- 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)` list 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.
+
+**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.
+
### §6.2 Subagent → orchestrator
-- Subagent's **final action before going idle** must be `SendMessage(to=<lead>)` with the page's JSON path and a ≤150-word text summary of findings + actions. Going idle without messaging is a protocol violation.
+- 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.
### §6.3 Orchestrator → main agent
diff --git a/skills/ppt-master/workflows/visual-review.md b/skills/ppt-master/workflows/visual-review.md
index 037dc9a6..1bc5f388 100644
--- a/skills/ppt-master/workflows/visual-review.md
+++ b/skills/ppt-master/workflows/visual-review.md
@@ -10,14 +10,23 @@ description: Per-page rubric-based visual self-review via parallel subagents. Ru
>
> This workflow is **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**, not a default step in the main pipeline. The Executor (SKILL.md Step 6) is already single-AI / single-session / continuous-generation — visual consistency across pages is built into that path. This workflow exists to give models with weaker visual reasoning an explicit "render → re-look → optimize" loop they wouldn't otherwise have.
+
+Trade-off to set expectations on:
+
+- **Token cost is significant.** Each batch subagent re-reads the rubric + `design_spec.md` + `spec_lock.md` 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.
+- **Marginal value scales inversely with the executing model's visual ability.** Strong-visual models (e.g., Claude 4.x) rarely produce the kind of letter-spacing / vertical-rhythm / collision drift this rubric targets; running visual-review on top of them mostly catches nothing. Weaker models benefit more — the rubric becomes a structured second pass that catches what they missed.
+
## When to Run
- Executor (SKILL.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
-- User wants to reduce manual review iterations before export
+- The executing model has known visual-quality gaps that a structured re-pass is likely to catch, **or** the deck is high-stakes enough that the extra token cost is worth a safety net
-Optional but recommended for any deck where layout precision matters. For decks containing data charts, run [`verify-charts`](./verify-charts.md) first — visual-review focuses on visual rhythm / collision / alignment, not chart coordinate math.
+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
@@ -25,6 +34,7 @@ Optional but recommended for any deck where layout precision matters. For decks
- `svg_quality_checker.py` has not been run or has failed — fix static violations first
- User has already applied annotations via `live-preview` workflow and is in a fixed-edit loop — describe changes directly, do not re-trigger rubric
- The deck is < 3 pages and the user is reviewing manually anyway — manual review is faster
+- The executing model already has strong visual reasoning — the token cost is unlikely to be recouped in fixes; skip unless there's a specific reason to double-check
---
@@ -67,7 +77,7 @@ If any page comes back with `"all_background": true` in the JSON summary, that p
## Step 2 — Spawn the review team
-Create a team and dispatch one orchestrator agent. The orchestrator spawns one per-page review subagent **in parallel** (single message, N parallel `Agent` calls), aggregates their JSON outputs, and reports back.
+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`) **once**, then iterates over its assigned pages sequentially.
```text
TeamCreate(team_name="visual-review-<project>", agent_type="orchestrator")
@@ -75,34 +85,21 @@ Agent(
team_name="visual-review-<project>",
subagent_type="general-purpose",
name="orchestrator",
- prompt=<orchestrator-prompt>, # see template below
+ prompt=<orchestrator-prompt>,
)
```
-### Orchestrator prompt template
-
-The orchestrator prompt must be self-contained. Required fields (all absolute paths):
+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
-- Page list with role for each page (parse `<project>/design_spec.md` §IX outline; if §IX is absent, default every page to `content` and flag this in the final report)
+- Full page list with `page_role` per page (parse `<project>/design_spec.md` §IX outline; if §IX is absent, default every page to `content` and flag this in the final report)
+- 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`
-- Instruction: **dispatch all per-page subagents in a single message**
-- Instruction: after aggregation, `SendMessage(to="team-lead")` with results before going idle — orchestrator must **not** end its turn without sending the aggregate
-
-### Per-page subagent prompt template
-
-Composed by the orchestrator, one per page, also self-contained:
-
-- SVG path, PNG path, `page_role`
-- Path to rubric
-- Path to `design_spec.md` and `spec_lock.md` (read-only)
-- Output JSON path: `<project>/.review/<page>.json`
-- Backup directory: `<project>/.review/backup/`
-- Iteration budget: 1 by default (2 for high-stakes decks — opt in explicitly)
-- Explicit forbid list: do not edit any other page, `design_spec.md`, `spec_lock.md`, `animations.json`, `image_prompts.json`, or `images/`
-- Mandatory final action: `SendMessage(to=<orchestrator-name>)` with the JSON path + a ≤150-word summary before going idle
+- 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`, `animations.json`, `image_prompts.json`, or `images/`
-See [`references/visual-review.md`](../references/visual-review.md) §6 for the full dispatch contract.
+**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.
---
@@ -165,13 +162,13 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>
---
-## Appendix: Iteration loop (v2 behavior)
+## Appendix: Iteration loop (opt-in)
-This v1 workflow uses single-iteration review (one scan, fix, done). The full iteration loop per [`references/visual-review.md`](../references/visual-review.md) §4.1 supports:
+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, pass `--iteration-budget 2` in the orchestrator prompt (currently advisory; the script itself does not enforce — subagent prompt must mention it explicitly). Reserve for final-cut runs.
+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.