---

name: slides-polish description: "Per-page Codex review + targeted python-pptx / Beamer fixes for academic talk slides. Use AFTER /paper-slides (or any externally generated PPTX/Beamer) when the deck looks 'mostly OK' but the user wants a final pass that aligns visual weight with a reference, bumps PPTX fonts to projector-readable size, kills italic style leaks, fixes text-frame overflow, and catches per-slide layout drift. Trigger phrases: "polish slides", "slides 排版不对", "PPTX 字体太小", "和 Beamer 比一下", "per-page review", "和 codex 一页一页过"." argument-hint: "[slides-dir-or-pptx] — reference: <ref-pdf> [— style: generic | why-rf | neurips | icml | iclr | cvpr] [— effort: lite | balanced | max | beast] [— interactive]" allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, mcp__codex__codex

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-6-astra — Codex MCP model for per-page review. xhigh reasoning is non-negotiable (see ../shared-references/effort-contract.md). If the account has no gpt-6-astra access, follow the capability fallback chain in ../shared-references/reviewer-routing.md (gpt-5.5+xhigh; gpt-5.4 only as an explicit user override).
• REVIEWER_REASONING = xhigh — Hard invariant; the effort knob does not change this.
• CONTEXT_POLICY = fresh — Each per-page review uses a fresh Codex thread (mcp__codex__codex, never codex-reply). 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: mcp__codex__codex 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

mcp__codex__codex:
  model: gpt-6-astra
  config: {"model_reasoning_effort": "xhigh"}
  sandbox: read-only
  prompt: |
    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 NO