latex-polish

name	latex-polish
description	Use when /latex reports a clean build but the document still needs a deeper visual-quality review. Runs the Phase 4 source-pathology lint AND renders selected PDF pages to images for vision-model inspection, catching rendered-output issues that grep cannot — weird title pages, clipped tables, bad float placement, illegible shrunken figures.
allowed-tools	Bash(ls*, mkdir*, cp*, pdftoppm*, pdftocairo*, pdfinfo*, grep*, sed*, awk*, find*, chktex*, latexindent*, cat*, head*, tail*, wc*, sort*, uniq*, rm*, mktemp*), Read, Write, Edit, Glob, Grep
argument-hint	[tex-path] [--no-vision] [--pages 'auto|1,3,5']

LaTeX Polish — Source Lint + Vision-On-Rendered-PDF

Heavier-weight visual-quality review than /latex. Combines the Phase 4 source-pathology lint with vision-model inspection of selected rendered PDF pages. Designed to catch the failure class that /latex Phase 4 source-grep misses: blank pages, clipped tables, illegible shrunken figures, weird title-page line spacing that the regex couldn't fingerprint, bad float placement, overlap.

When to Use

• Pre-submission visual check on a paper, proposal, thesis, or deck
• After major restructuring (new sections, table re-layouts, figure swaps) when you want eyes on the rendered output
• When /latex reports a clean build but something still "looks weird"
• When preparing for a panel / supervisor read where presentation matters

When NOT to Use

Need	Use instead
Compile-fix loop	/latex
Citation audit	/latex (Phase 5) or /bib-validate
Prose / academic-argument review	/proofread
Single-figure analysis	/figure-feedback
Continuous integration	This skill renders + vision-inspects pages; too expensive to run on every save

Inputs

• .tex path — auto-discovered or user-provided. Prefer the user's argument.
• PDF path — assumed at <project>/<basename>.pdf (per /latex convention). If absent or older than .tex, the skill aborts and suggests /latex first.
• --no-vision — skip the vision-rendering phases (Page rendering onward), run the source-pathology lint only.
• --pages auto|N,N,N — page selection override. Default auto.

Hard Rules

1. Do not compile. This skill presupposes a clean PDF. If the PDF is missing or stale, abort and suggest /latex first.
2. Read-only with respect to source files. Exception: Pattern-1 (spacing-hack) opt-in fix, which is offered with a diff and only applied on explicit user yes.
3. No deploy actions. This skill produces a report; it does not commit, push, or modify build infrastructure.
4. Cap render cost. Max 8 pages rendered per invocation. If page selection would exceed 8, prioritise: title page, worst-overfull page, first table/figure page, then arbitrary sample.
5. Cap vision-prompt cost. One Read per rendered page. No per-page back-and-forth.

Protocol — 7 Phases

Phase 1: Pre-flight

1. Resolve .tex path. If a directory was given, find main.tex or single .tex inside.
2. Resolve PDF path: <dirname>/<basename without .tex>.pdf. If missing or older than .tex, abort with: "Stale or missing PDF — run /latex first."
3. Verify pdftoppm is on PATH. If not, abort with install hint (brew install poppler on macOS).
4. Create render dir: mktemp -d /tmp/latex-polish.XXXXXX. Track this as $RENDER_DIR.

Phase 2: Source-pathology re-run (Phase 4 of /latex)

Run the 9 grep-based source-pathology detectors from ~/.claude/skills/latex/references/source-pathologies.md, plus chktex and latexindent -k if installed. Collect findings into a structured list.

This phase is identical to /latex Phase 4 and is rerun here for self-containment (so /latex-polish can be invoked without a prior /latex run).

Phase 3: Page selection

Determine which pages to vision-inspect. Default auto:

Page	Why	Mandatory if available
1	Title / cover — high-stakes visual real estate; title-page failure mode is common	Yes
Page containing any overfull vbox > 50pt	Vertical overflow is almost always visually broken	Yes
Page containing the largest overfull hbox	The "worst" horizontal overflow seen	Yes
First page containing a table	Tables produce the most common visual pathologies	Yes
First page containing a figure	Same	If figures exist
Last body page before bibliography	Catches widow/orphan and end-of-content layout issues	If pages > 5
Bibliography page 1	Citation formatting + hanging indent regressions	If bib exists

If overfull-box locations are not known (no log file or out/main.log missing), skip those entries. Cap total at 8 pages; if the selection would exceed 8, drop the lowest-priority entries.

Pull overfull-box page locations by reading <project>/out/<basename>.log:

awk '/Overfull \\(v|h)box/ { for(i=1;i<=NF;i++) if($i ~ /\[[0-9]+\]/) print substr($i,2,length($i)-2) }' out/main.log | sort -u

For each candidate page, also record WHY it was selected (used to pick the right vision-prompt later).

Phase 4: Page rendering

for P in $SELECTED_PAGES; do
    pdftoppm -r 150 -f $P -l $P -png "$PDF" "$RENDER_DIR/page-$P"
done

150 DPI is enough for layout analysis without ballooning file sizes. Each PNG lands at $RENDER_DIR/page-<N>-<P>.png (pdftoppm pads the page number).

Phase 5: Vision analysis

For each rendered page, Read the PNG and apply the per-page-type prompt from references/vision-prompts.md:

• Title page prompt: focuses on alignment, line-spacing consistency, weight hierarchy, vertical block separation, font-size jumps
• Body page prompt: focuses on paragraph spacing, hyphenation/justification artefacts, ragged margins, widow/orphan lines, float positioning
• Table/figure page prompt: focuses on caption position, alignment with surrounding text, legibility at this rendered size, clipping, awkward whitespace
• Bibliography page prompt: focuses on hanging indent, entry alignment, consistent inter-entry spacing
• General prompt: catches anything unmatched

Each Read produces a structured finding list per page. Output schema per page:

Page N (selection reason: "title page" | "overfull at L<line>" | …):
  - Finding 1: <one-sentence description> [Tier: Major/Moderate/Minor]
  - Finding 2: …
  Verdict: PASS / NOTES / REVISE

If --no-vision was passed, skip Phases 3–5 entirely.

Phase 6: Report consolidation

Write the polish report to <project>/reviews/<paper-slug>/latex-polish/<YYYY-MM-DD-HHMM>.md (per rules/review-artefact-routing.md), where <paper-slug> is the paper being reviewed (e.g. paper-jtp, paper-philtech):

# LaTeX Polish Report — YYYY-MM-DD HH:MM

**Document:** <path>
**PDF age:** <minutes/hours since last build>
**Pages rendered for vision:** N
**Source detectors run:** 9 grep + chktex + latexindent

## Source pathologies (Phase 2)

<table from Phase 4 spec>

## Per-page vision findings (Phase 5)

### Page 1 — title
<verdict and findings>

### Page <N> — <reason>
<verdict and findings>

...

## Consolidated verdict

PASS / NOTES / REVISE — based on the worst finding tier across both phases.

## Suggested remediations

<prioritised list, max 10 items>

Phase 7: Quality score

Read references/quality-rubric.md. Compute deductions across:

• Source-pathology findings (mirrors /latex rubric)
• Vision findings (this skill's distinct contribution)

Verdict thresholds per skills/shared/quality-scoring.md. Append the Score Block to the report.

Pattern-1 opt-in auto-fix

If Phase 2 detects a Pattern-1 (spacing-hack) issue, the report includes an **Offer:** block:

**Offer:** Wrap `<env-name>` in `\begin{singlespace}…\end{singlespace}` and delete the negative kerns at L<N1>, L<N2>. Apply? (Y/N)

Wait for explicit user approval. If yes, apply via narrow Edit calls and recompile via latexmk. If no, leave the report as-is. Do not silently apply.

This is the only auto-fix offered. All other findings are report-only.

What /latex-polish does NOT do

• Compile or fix compile errors (use /latex first)
• Modify prose or argument (/proofread covers that)
• Audit citations (/latex Phase 5 or /bib-validate)
• Replace /figure-feedback for standalone figure-file analysis
• Auto-commit, auto-push, or modify settings.json / hooks / rules

Cross-references

Skill / File	Relationship
/latex	Compile + Phase 4 grep lint + citation audit. /latex-polish is the deeper sibling for visual-quality review.
/figure-feedback	Vision pattern this skill reuses for per-page analysis
/proofread	Prose / argument review; non-overlapping concern
~/.claude/skills/latex/references/source-pathologies.md	Shared detector catalogue
rules/review-artefact-routing.md	Where the polish report is filed
rules/manuscript-edit-budget.md	Why this skill is report-only by default