slides-polish

Files (1)

• SKILL.md

SKILL.md (first lines)

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

> **Before each reviewer slot**, follow [Selectable Reviewers](../shared-references/reviewer-backends.md):
> resolve invocation → `.aris/reviewer.json` → Codex default (fresh native reviewer)
> with `reviewer_route.py` through the canonical helper resolver, preserving this
> slot's tier, fresh contexts, source/image inputs and deterministic gates.
> Codex examples/pins below apply only to `backend=codex`; other routes use their
> own first-call/reply contract. Save the route and actual returned identity;
> unavailable selections are `REVIEW_UNAVAILABLE`. Classify acceptance from actual
> families/completion/scope. Forward invocation reviewer/model/effort overrides
> to reviewer-bearing children. Generation workers are unchanged.


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 canonical capability fallback chain in `../shared-references/reviewer-routing.md` (the model fallbacks start with `gpt-6.1-sol`+`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 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).
- **Selected reviewer**: resolve the route before Phase 0. If unavailable, stop with `REVIEW_UNAVAILABLE`; do not silently select another provider. Its image/PDF input capability must satisfy the per-page visual review.

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

From wanshuiyin/Auto-claude-code-research-in-sleep, MIT.

More from wanshuiyin/Auto-claude-code-research-in-sleep