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:
   • A directory containing *.pptx, or talk_beamer/main.tex + main.pdf, or both.
   • A specific file path (talk.pptx or main.tex).
2. Reference PDF (— reference: <path>, REQUIRED). If not supplied, the skill prompts the user. Do not silently substitute.
3. Style preset (— style: <preset>, default generic). Influences color hex codes and element library; see Style Presets below.
4. Effort (— effort: lite | balanced | max | beast, default balanced). See Effort Levels.
5. 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 --headless --convert-to pdf). If unavailable, prompt user to export.
6. Render PDF → PNG: pdftoppm -r 150 <pdf> .aris/slides-polish/<stem>/png/page produces one PNG per slide; passed to Codex during per-page review.
7. Triage pass: a single fresh Codex call sweeps all N slides comparing PPTX-PDF (or Beamer PDF) against the reference. Output: per-slide verdict matrix.

Inspector contract

The skill ships a contract for inspect_pptx.py rather than a fixed implementation. On first run, if the script is absent under .aris/slides-polish/<deck-stem>/inspect_pptx.py, create it from this contract. Implementations may evolve; the contract is what downstream phases depend on.

CLI:

python3 inspect_pptx.py --pptx <input.pptx> --out <state-dir>/INSPECT_<stem>.json
# exit 0 on success, 2 on missing python-pptx, 3 on parse failure

Recurse through groups; surface table cells and placeholders. Convert all geometry from EMU to inches via EMU_PER_INCH = 914400. Compute notes_text_hash as sha256(notes_text) for byte-level integrity check in Phase 4. Schema:

{
  "slide_count": 22,
  "slide_size_in": [13.33, 7.5],
  "slides": [
    {
      "index": 0,
      "page_number_text": "1 / 22",
      "has_notes": true,
      "notes_text_hash": "sha256:…",
      "shapes": [
        {
          "id": "13",
          "name": "TextBox 3",
          "shape_path": ["13"],
          "parent_group_ids": [],
          "type": "TEXT_FRAME",
          "placeholder_type": null,
          "table_cell": null,
          "text": "ARIS",
          "runs": [
            {"text": "ARIS", "font_pt": 80.0, "bold": false,
             "italic": false, "color_rgb": "1F1F1F"}
          ],
          "bbox_in": {"left": 0.5, "top": 1.6, "width": 12.33, "height": 0.95},
          "fill_rgb": null,
          "line_rgb": null,
          "image_size_px": null
        }
      ]
    }
  ]
}

Schema notes:

• shape_path: list of shape IDs from outermost group to leaf shape.
• parent_group_ids: empty if shape is at the slide root.
• type: one of TEXT_FRAME | PICTURE | AUTO_SHAPE | GROUP | TABLE | CONNECTOR | PLACEHOLDER.
• placeholder_type: e.g., TITLE | BODY | OBJECT | NONE.
• table_cell: {row, col} if shape is a table cell, else null.
• All hex colors are 6-char uppercase, no leading #.
• All geometry in inches, rounded to 4 decimals.

Triage Codex prompt

spawn_agent:
  model: gpt-5.5
  reasoning_effort: xhigh
  message: |
    Triage pass. For each of N slides in <pptx-pdf-path>, compared against
    <reference-pdf-path>, give one line:

      Slide K | PASS | NEEDS-WORK | BLOCKER — <one-sentence reason>

    Focus on: visual-weight match, text-frame overflow, page-number overlap,
    awkward title wraps, italic style leaks, Chinese tofu/missing-glyph
    boxes, callout-box color discipline, anonymity leaks (e.g., real titles
    appearing where placeholders should be).

    Do NOT rewrite content. Do NOT propose font scaling for slides that
    already read fine. Do NOT comment on speaker notes.

    End with a one-line summary: "K BLOCKERS, K NEEDS-WORK, K PASS."

Save matrix to TRIAGE.md. Present to user before deep work begins.

Phase 1: Per-Page Review + Fix Loop

For each slide flagged NEEDS-WORK or BLOCKER, run a focused fresh-thread Codex call. Apply the returned fix immediately (subject to INTERACTIVE), recompile or save, move to next slide.

Per-page loop, not batch. Empirically: per-page Codex calls converge in 1-2 polish rounds where single-pass batch review never converges.

Per-page Codex prompt template

spawn_agent:
  model: gpt-5.5
  reasoning_effort: xhigh
  message: |
    SLIDE K review. Compare PPTX page K against reference page K.

    Files:
    - PPTX page rendering: <png-path>/page-K.png
    - Reference page rendering: <ref-png-path>/page-K.png
    - Source: <pptx-file-path> (slide index K-1) and/or <main-tex-path>
    - Inspector inventory for slide K: <inspect-json-slide-K-snippet>

    Slide K title (from inventory): "<title>".

    Style anchor: <style-preset> + reference PDF.

    Give:
    1. Status: PASS / NEEDS-WORK / BROKEN
    2. What's working (1-2 specifics)
    3. What's drifting vs reference (1-3 specifics)
    4. Concrete python-pptx (or .tex) fixes:
       - Identify shapes by their text content (NOT by index — index drifts).
       - Use unique-prefix substring matching; if duplicate matches, abort
         and request human disambiguation rather than touching the first.
       - Give before/after snippets.
    5. If a fix would change CONTENT (claims, numbers, anonymity placeholder
       text, etc.), STOP and report it instead of suggesting it.

    End: VERDICT: PASS | NEEDS-WORK | BROKEN. Under 500 words.

Fix application

After Codex returns, call apply_fix(slide_index, fix_block) which:

1. Loads the _polished working copy.
2. Locates each target shape by text_frame.text substring; asserts unique match or aborts.
3. Applies edits (font size, position, color, italic, line spacing).
4. Saves atomically (write to tmp + rename).
5. Logs the change to POLISH_CHANGELOG.md (one line: Slide K | <change> | reason).

After every 3 slides, write a checkpoint snapshot <stem>_polished_checkpoint_KK.pptx.

Robust shape selection

def find_shape(slide, contains: str, *, kind: str | None = None):
    """Return the unique shape whose text_frame.text contains `contains`.
    Aborts if duplicate matches (caller must disambiguate by bbox or kind).
    """
    matches = []
    for sh in slide.shapes:
        if not sh.has_text_frame:
            continue
        if kind is not None and sh.shape_type != kind:
            continue
        if contains in sh.text_frame.text:
            matches.append(sh)
    if len(matches) == 0:
        raise LookupError(f"no shape contains {contains!r} on slide")
    if len(matches) > 1:
        raise AmbiguousMatch(f"{len(matches)} shapes contain {contains!r}; "
                             f"need disambiguator (kind, bbox, or longer needle)")
    return matches[0]

For grouped shapes, recurse into shape.shapes if shape_type == GROUP.

Phase 2: Beamer-Side Polish (if Beamer source present)

Same per-page review pattern, but on main.tex source + compiled PDF. Fixes are direct Edit tool operations on a main_polished.tex working copy followed by xelatex recompile and PNG re-render. The original main.tex is preserved.

Common Beamer fix patterns (inline catalog — no external file required)

These are encoded directly in this SKILL.md so the skill has zero external dependencies:

• Frame title size + thin underline rule: use beamercolorbox template with \hrule height 0.55pt AFTER the title text, NOT a bare \rule{} outside the beamercolorbox (which renders top-right, not under title).
• \sectionlabel macro for small caps blue mini-headers:

  \newcommand{\sectionlabel}[1]{%
    {\sffamily\fontsize{8}{10}\selectfont
     \textcolor{<accent>}{\textls[200]{\MakeUppercase{#1}}}}}
  

  Requires microtype for \textls.
• array package for >{\raggedright\arraybackslash}p{Xcm} in cards. Without it, tabular cells justify and create rivers / mid-word hyphenation in narrow columns.
• Banner = real tcolorbox, not \begin{center}\color{...} (which renders as plain centered text, not a banner).
• Em-dash spacing: prefer \textemdash{} (with explicit braces) or \,---\, over a bare —. A bare em-dash often renders with collapsed surrounding whitespace.
• Color-leak inside \sectionlabel: \sectionlabel{... \textcolor{red}{...}} BREAKS because \MakeUppercase uppercases color name → undefined-color error. Put \textcolor outside or define a colored \sectionlabel* variant.
• CJK + math: with xelatex, use \usepackage[fontset=fandol]{ctex} or set EA fonts explicitly. Mixed Chinese-English in titles needs the EA font hint or characters fall back to Latin.

Phase 3: PPTX-Side Polish

Apply font scaling first (Phase 3a), then layout fix loop (Phase 3b). Bumping fonts without resizing frames creates overflow.

Phase 3a: Font scaling (heuristic table)

Compute target sizes from Beamer reference using PPTX_SCALE_HINT. Reference mapping:

Page-number rule: never bump page numbers above 16pt. They stay small.

After scaling, always revisit Phase 1 triage — the 1.6× hint is a starting point; some slides need 1.5×, some 1.8×.

Phase 3b: Text-frame layout fix loop

Two recurring failure modes after font bump:

1. Title overlaps subtitle/body: a title at 100pt sits in a 0.95"-tall frame but the glyph is ~1.4" tall, so it bleeds down. Fix: increase the text frame height AND reposition the next-element top.
2. Body bullets wrap mid-sentence: a long-noun-phrase bullet wraps with the final noun alone on the next line because the frame width is sized for the old (smaller) font. Fix: widen the frame AND narrow the adjacent column.

Each per-page Codex call returns specific shape resize commands; apply via the inspector's bbox primitives.

Phase 3c: Common PPTX pitfalls (inline catalog)

• Image aspect ratio: bumping width without height stretches embedded PNGs. Always compute height = width × (image_height_px / image_width_px).
• Banner = real filled rectangle: use tcolorbox-equivalent (in PPTX, a separate MSO_SHAPE.RECTANGLE behind the text frame), not just colored text.
• Curved arrows: python-pptx has no curved-arrow primitive. Approximate with two straight MSO_CONNECTOR_TYPE.STRAIGHT connectors (vertical + horizontal) or use an add_freeform Bezier. Document the approximation.
• Italic style leak: \itshape in the source without braces causes all following runs in the same paragraph to inherit italic. Wrap as {\itshape ...} or scope to a single run.
• Chinese rendering: PowerPoint needs the East Asian font hint (<a:ea typeface="PingFang SC"/> for macOS, Microsoft YaHei for Windows). Without it, characters fall back to a Latin font and render as tofu boxes.
• Em-dash spacing: bare — in titles often renders with collapsed spaces. Insert literal spaces (" — ") or use figure-space.
• Cycle-arrow / feedback-loop labels: ensure label bbox stays inside slide bounds (L > 0.4in, T > 0.4in). PPTX silently clips off-slide content, and curved labels positioned near the left/top edge are the most common offenders.
• Anonymity placeholder discipline: ALL placeholders for under-review work must use generic phrasing (e.g., "Withheld for anonymous review", "[anonymized]"). NEVER infer or fill in real titles, counts, or URLs. See ../shared-references/experiment-integrity.md.

Phase 4: Verification + Re-Triage

1. Re-render PPTX → PDF (LibreOffice or user-export).
2. Re-render PDF → PNG for visual.
3. Re-triage: rerun Phase 0.7 prompt. Goal: 0 BLOCKERS, ≤2 NEEDS-WORK. If > 2 NEEDS-WORK remain, loop back to Phase 1 for those slides.
4. Speaker-notes integrity check: assert every slide's notes_slide is present and unchanged from _pre_polish.pptx (a polish round must never touch notes content).
5. Anonymity scan: grep the final PPTX for known sensitive strings (real author names absent from the original, real URLs added by the LLM, real submission counts). If found, fail closed and report.
6. Final emit: <stem>_polished.pptx (and .pdf if rendered).

Phase 5: Changelog

Write POLISH_CHANGELOG.md:

Slide  1 cover  | bumped wordmark 80→86; subtitle 36→40; line spacing 0.9        | Codex per-page review
Slide  2 hook   | left body L=0.45 W=8.30; right cards 28→19pt; yellow strip 22→19 | wrap fix
Slide  3 …      | …                                                              | …

This makes every polish round auditable and reversible (each line maps to a _polished_v{i} checkpoint).

Style Presets

Presets influence default colors and the element library only — the reference PDF is always the visual ground truth, not the preset.

generic (default)

Black + one accent (default #2563EB). No callout-box fills beyond a single neutral background where load-bearing.

why-rf (academic-minimalist, example preset)

Anchor: a 2025 academic talk on rectified flow with the following discipline.

Color palette (load-bearing only, sparingly):

• Primary accent (e.g., #2E75B6)
• Darker accent (chip backgrounds, big numbers, e.g., #1F4E79)
• Light callout bg (e.g., #DEEBF7)
• Honest-disclosure yellow (e.g., #FFF4CC)
• Audit-bug red (safety disclaimers only, e.g., #C00000)
• Page gray (e.g., #808080)
• Text dark (e.g., #1F1F1F)

Element library (used sparingly):

• chorebox: white bg + thin top accent rule + section-label + bold title + body
• eqbox: light-accent full-width banner; load-bearing assumption / conclusion only
• yellowstrip: honest-yellow + 3pt left-edge orange rule; honest disclosures only
• redbox: light red + red border; safety disclaimers only
• banner: light-accent full-width strip; brief banner caption

Discipline: fewer color boxes than typical "designerly" templates. Cosmetic cards become plain bullets; marketing flourishes are removed.

neurips / icml / iclr / cvpr

Inherit color schemes from /paper-slides. Polish-loop and font-scaling rules unchanged.

Effort Levels

See ../shared-references/effort-contract.md for the full contract.

reasoning_effort: xhigh is non-negotiable across all levels.

Hard Invariants

These are non-negotiable:

1. Reference is required. The skill never polishes without an explicit visual anchor. If no reference PDF, ask the user. A style preset is not a substitute.
2. Original is never overwritten. All edits target <stem>_polished.<ext>; the snapshot at <stem>_pre_polish.<ext> is the rollback target.
3. Speaker notes are preserved verbatim. Every PPTX edit must preserve slide.notes_slide content. Phase 4.4 verifies this byte-for-byte against the snapshot.
4. No content edits. No new claims, numbers, citations, URLs, author names, affiliations, or experiment results. No equation or figure-content changes. No paraphrasing of body text — only style/typography/box edits. If a Codex fix proposal would change content, the skill stops and reports it.
5. No slide reordering, addition, or deletion unless the user passes an explicit flag (— add-slide-K-after-J, — drop-slide-K).
6. Cross-model independence: per-page Codex calls are fresh spawn_agent calls, not send_input. Reviewer never sees prior fix lists. See reviewer-independence.md.
7. Anonymity placeholders fail closed. If a Codex fix proposes filling in a real title, count, or URL where a placeholder was, the skill rejects it and surfaces the proposal for human review. See experiment-integrity.md.
8. Page numbers stay ≤ 16pt. Why-RF discipline; never bump them.
9. reasoning_effort: xhigh is invariant across all effort levels.
10. Robust shape selection: edits use unique-prefix text_frame.text matching with assert-unique semantics. If duplicate matches, abort and request disambiguation.

Review Tracing

After each per-page Codex call, save the trace following ../shared-references/review-tracing.md. Per-call file under .aris/slides-polish/<stem>/traces/slide_KK.json with:

• Codex agent_id
• prompt (verbatim)
• response (verbatim)
• applied diff summary (list of shape edits with before/after sizes/bboxes)
• validation status (post-fix re-render PASS/FAIL)

Both the triage pass and the per-slide passes are traced.

Prior Skill Relationship

• Runs after /paper-slides (or any externally generated deck).
• Compatible with /paper-poster-html workflow (same color discipline) but different output cadence.
• Uses the same spawn_agent MCP infrastructure as /auto-paper-improvement-loop, /research-review, etc.
• Does not call or compose with /paper-slides content phases — strict separation.

When NOT to Use

• Slides are still in content drafting phase — go back to /paper-slides Phases 1-2.
• Complete redesign needed (different colors / template / aspect ratio) — re-run /paper-slides, not polish.
• Deck has fewer than 5 slides — per-page review overhead is not worth it; hand-edit.
• The user explicitly says "no Codex" — this skill is Codex-driven by design.

Empirical Origin

This skill was extracted from a polish run on a Chinese-spoken academic conference talk (May 2026). The convergent observation: once content is locked, the remaining cost is per-page visual fidelity — and per-page Codex review with concrete python-pptx / .tex fix snippets converges in 1-2 rounds where single-pass batch review never converges. The fix-pattern catalogs in Phases 2-3 (Beamer template gotchas, PPTX font scaling, layout fix loop, Chinese-font hints) are the durable artifact.

Parameter Pass-Through

When invoked via /research-pipeline or another orchestrator, parameters flow as:

• — effort → see Effort Levels.
• — reference → REFERENCE_VISUAL.
• — style → STYLE_PRESET.
• — interactive → INTERACTIVE = true.

Other args (e.g., — venue) are ignored by this skill and not propagated.