slides-polish

Slides Polish: Per-Page Codex Review + Targeted Layout Fixes

Polish a generated slide deck — Beamer (.tex + .pdf) and/or PPTX — by running per-page Codex review against a reference visual and applying surgical fixes (font scaling, text-frame resize, callout-box style, em-dash spacing, anonymity placeholders, Chinese-font hints, italic style leaks) until each slide reads at the same visual weight as the reference.

Polish: $ARGUMENTS

What This Skill Is — and Is NOT

This skill polishes layout and typography only. It is the post-generation visual pass for an existing deck.

Hard scope rules (load-bearing — see Hard Invariants):

• It does not rewrite content, claims, numbers, citations, URLs, author

names, affiliations, or experiment results.

• It does not add, remove, or reorder slides unless the user explicitly

asks (e.g., — add-slide / — drop-slide flags).

• It does not generate outlines, speaker scripts, or new Beamer/PPTX from

paper source. That is /paper-slides's job.

• It does not change figures or equations content.

If you do not yet have a deck, run /paper-slides first. If you want to change content, go back to /paper-slides Phases 1-2 (or rewrite the outline manually) — do not run /slides-polish for that.

Constants

• REVIEWER_MODEL = gpt-5.5 — Codex MCP model for per-page review. xhigh reasoning is non-negotiable (see ../shared-references/effort-contract.md). gpt-5.4 is acceptable when the user has no gpt-5.5 access; gpt-5.5 is preferred for visual nuance.
• REVIEWER_REASONING = xhigh — Hard invariant; the effort knob does not change this.
• CONTEXT_POLICY = fresh — Each per-page review uses a fresh Codex reviewer call (spawn_agent, never send_input). See ../shared-references/reviewer-independence.md. This prevents the reviewer from anchoring on prior fixes.
• REFERENCE_VISUAL — Path to a PDF the user wants the polished deck to align with in visual weight (typography proportion, color discipline, callout density). Required input. If polishing PPTX only, the Beamer compile of the same talk is the ideal reference. If no reference exists yet, ask the user; do not silently default to "Why-RF" or any preset.
• STYLE_PRESET = generic — Default style anchor. Other options: why-rf (academic-minimalist, derived from a 2025 academic talk), neurips, icml, iclr, cvpr. Presets influence color discipline + element library; the reference PDF is the visual ground truth, not the preset.
• PPTX_SCALE_HINT = 1.6× — Heuristic multiplier from Beamer point sizes to PPTX point sizes for matched visual weight on 13.33"×7.5" PowerPoint at 16:9. Range 1.5-1.8×. The actual scale is always validated by visual review, never blindly applied.
• INTERACTIVE = false — When false, applies the recommended fix automatically and continues to the next slide. When true (— interactive), pauses for user confirmation before each fix.
• OUTPUT_VERSIONING = on — Output is a versioned file named <input-stem>_polished.<ext> (or _polished_v2, _v3, …). Snapshot of the input is preserved as <input-stem>_pre_polish.<ext>. The original is never overwritten. All edit operations target the _polished working copy.

💡 Override examples

- /slides-polish talk_pptx/talk.pptx — reference: talk_beamer/main.pdf — style: why-rf

- /slides-polish talk_beamer/ — reference: ./reference_talk.pdf — style: generic — effort: max

- /slides-polish talk.pptx — reference: ./why_rf_2025.pdf — interactive

Prerequisites

The skill discovers and reports missing prerequisites at Phase 0; it does not auto-install. Required:

• Python: python3 with python-pptx>=0.6 (pip install python-pptx).
• PDF inspection: pdfinfo and either pdftoppm (poppler, preferred) or mutool draw (mupdf) for rendering slides to PNG. Required so the per-page Codex call sees actual slide pixels, not text extraction alone. Render command: pdftoppm -r 150 -png <pdf> <out-stem> (or mutool draw -o <out-stem>-%d.png -r 150 <pdf>).
• PPTX → PDF rendering: soffice (LibreOffice headless) preferred; otherwise the user must export PDF manually from PowerPoint/Keynote.
• LaTeX (Beamer side only): xelatex (CJK) or pdflatex, plus latexmk for clean recompiles. The Beamer fix patterns in Phase 2 may require these LaTeX packages: microtype (letter-spacing in section labels), array (raggedright p-columns), tcolorbox (banners and callouts), ctex or xeCJK (CJK), tikz + tikz-cd (diagrams).
• Codex MCP: spawn_agent must be available (the user must be signed in to Codex MCP). The skill aborts at Phase 0 if Codex MCP cannot be reached.

Fallback rules:

• If pdftoppm/mutool missing → ask user to install, do not proceed (visual review without rendered pages produces low-confidence Codex feedback).
• If soffice missing and PPTX is the input → ask user to export PDF from their slide tool; resume after.

Inputs

Discovered automatically from $ARGUMENTS and the project directory:

1. Slides source:
2. A directory containing *.pptx, or talk_beamer/main.tex + main.pdf, or both.
3. A specific file path (talk.pptx or main.tex).
4. Reference PDF (— reference: <path>, REQUIRED). If not supplied, the skill prompts the user. Do not silently substitute.
5. Style preset (— style: <preset>, default generic). Influences color hex codes and element library; see Style Presets below.
6. Effort (— effort: lite | balanced | max | beast, default balanced). See Effort Levels.
7. Interactive flag (— interactive). Pauses after each per-slide fix.

Output Layout

<deck-dir>/
├── <stem>.pptx                       # original (untouched)
├── <stem>_pre_polish.pptx            # snapshot before any edit
├── <stem>_polished.pptx              # versioned working output
├── <stem>_polished.pdf               # rendered (when conversion available)
└── ... (Beamer files mirrored)

.aris/slides-polish/<deck-stem>/
├── POLISH_STATE.json                 # phase + per-slide status + version pointer
├── INSPECT_<stem>.json               # pre-polish shape inventory
├── TRIAGE.md                         # Phase-1 verdict matrix (per-slide PASS/NEEDS-WORK/BLOCKER)
├── POLISH_CHANGELOG.md               # per-slide fix log (auditable)
└── traces/                           # codex traces (per-slide review JSON, see review-tracing.md)
    ├── slide_01.json
    ├── slide_02.json
    └── ...

The skill keeps a self-contained cache under .aris/slides-polish/<deck-stem>/. Per-call Codex traces also follow the shared convention .aris/traces/slides-polish/<date>_runNN/ per ../shared-references/review-tracing.md. Resumable across sessions if POLISH_STATE.json exists with "status": "in_progress" and is < 24h old.

Note: existing skills like /paper-slides may use a co-located state file (e.g., slides/SLIDES_STATE.json). /slides-polish keeps its state in .aris/ to keep the deck directory free of polish-specific cruft.

Workflow

Phase 0: Inventory, Inspect, Triage

1. Discover inputs: parse $ARGUMENTS; locate slides files; check prerequisites; emit a brief inventory report.
2. Confirm reference PDF: validate the file exists and has the same slide count (or at least ≥ slide count) as the input. If a mismatch, ask user.
3. Inspect shapes: run the inspector (Phase 0 sub-step below) to produce INSPECT_<stem>.json listing every text-frame and shape on every slide with: shape id, type, text content (escaped), font sizes per run, bbox in inches, fill/line color, image dimensions for pictures, presence of speaker notes. This file is the ground truth for "find shape by text" downstream.
4. Snapshot original: cp <stem>.pptx <stem>_pre_polish.pptx (and .tex if Beamer present). All subsequent edits target _polished copy.
5. Render PPTX → PDF if needed (`soffice --headl