verify-visual — visual verification loop

This is a workflow skill that runs only when verification is requested. The loop is:

compile → render → analyze → (if fail) propose fix → recompile → re-render → ...

with a budget. Default budget: 3 iterations.

Step 0 — Prerequisites

Detect available tools (run once):

command -v pdftocairo >/dev/null && echo "PDFTOCAIRO=ok"   # preferred renderer
command -v pdftoppm   >/dev/null && echo "PDFTOPPM=ok"     # fallback
command -v mutool     >/dev/null && echo "MUTOOL=ok"       # MuPDF fallback
command -v diff-pdf   >/dev/null && echo "DIFFPDF=ok"      # optional, for reference-diff
command -v compare    >/dev/null && echo "COMPARE=ok"      # optional, ImageMagick SSIM
command -v pdfinfo    >/dev/null && echo "PDFINFO=ok"      # poppler-utils
command -v pdffonts   >/dev/null && echo "PDFFONTS=ok"     # poppler-utils

If no renderer is available, install poppler-utils (apt install poppler-utils, brew install poppler, pacman -S poppler).

Step 1 — Compile

Invoke /academic-latex:compile to produce <main>.pdf. If compile fails, the loop stops and surfaces the error from /academic-latex:debug.

Step 2 — Structural checks

Run these against the produced PDF:

PDF=<main>.pdf
LOG=<main>.log

# Page count
PAGES=$(pdfinfo "$PDF" | awk '/^Pages:/ { print $2 }')

# Fonts embedded? Any unembedded font is a journal-grade red flag.
pdffonts "$PDF" | awk 'NR>2 && $4 != "yes" { print "Unembedded font:", $1 }'

# Overfull/underfull boxes from latest log
grep -E '^(Overfull|Underfull) \\[hv]box' "$LOG" | head -20

# Undefined references / citations remaining?
grep -E "LaTeX Warning: (Reference|Citation) .* undefined" "$LOG" | sort -u

# Float placement issues
grep -E "Float .+ pushed" "$LOG" | head -5

Surface a numbered list of findings. Distinguish fail (unembedded fonts, undefined refs/cites) from warn (overfull boxes < 5pt, float-push warnings).

Step 3 — Render representative pages

DPI=200                                   # 200 is right for typography review; bump to 300 for fine grain
OUT=verify-out
mkdir -p "$OUT"
# Cover page + first content + last:
pdftocairo -png -r $DPI -f 1 -l 1 "$PDF" "$OUT/p"
pdftocairo -png -r $DPI -f 2 -l 2 "$PDF" "$OUT/p"
LAST=$PAGES
pdftocairo -png -r $DPI -f $LAST -l $LAST "$PDF" "$OUT/p"

For a thorough pass, render all pages: pdftocairo -png -r $DPI "$PDF" "$OUT/p". Note: at 200 DPI a typical paper is ~10MB per page in PNG.

If pdftocairo is missing, fall back to pdftoppm -png -r $DPI -f N -l N or mutool draw -o page.png -r $DPI <pdf> N.

Step 4 — Visual analysis

The model reads the rendered PNGs (Read tool on image files). Look for:

Don't enumerate trivial differences (anti-aliasing jitter is normal). Flag substantive issues only.

Step 5 — Reference comparison (optional)

If the user provides a reference PDF (e.g., previous submission, expected output):

Quick yes/no with diff-pdf

diff-pdf --output-diff=verify-out/diff.pdf reference.pdf "$PDF"
echo $?    # 0 = identical, 1 = differ

The output diff.pdf highlights every visual difference page-by-page. Inspect by rendering its pages.

Threshold-tolerant with SSIM (ImageMagick)

pdftocairo -png -r 200 reference.pdf verify-out/ref
pdftocairo -png -r 200 "$PDF" verify-out/cur
for p in verify-out/ref-*.png; do
  base=$(basename "$p" | sed 's/^ref/cur/')
  ssim=$(compare -metric SSIM "$p" "verify-out/$base" /dev/null 2>&1)
  echo "$base SSIM=$ssim"
done

SSIM > 0.99 ≈ visually identical (account for font-rasterization jitter). Lower → real divergence.

Source: https://github.com/vslavik/diff-pdf, https://imagemagick.org/script/compare.php.

Step 6 — If checks fail, propose fixes

For each failure, suggest a specific fix. Examples:

• Unembedded font → \usepackage[T1]{fontenc} (pdflatex) or set \setmainfont{...} to an installed family (xelatex/lualatex).
• Undefined reference → look at the .aux; check for typos in \label/\ref keys.
• Undefined citation → run bib backend; verify .bib has the key.
• Overfull \hbox > 10pt → add \sloppy to the offending paragraph or hyphenate manually.
• Wrong caption position → it's the class default; if journal-required, override with \captionsetup.
• Missing figure (caption with no image) → \includegraphics path; check file exists.
• Garbled CJK → wrong engine; switch to xelatex/lualatex; load xeCJK/luatexja/ctex.

Do not auto-apply fixes without surfacing them. Confirm with the user (or use /academic-latex:author to apply if explicitly authorized for an autonomous loop).

Step 7 — Iterate

If the user asked for an autonomous loop ("keep fixing until it's right"), repeat steps 1–6 up to the budget (default 3). If the budget exhausts, stop and surface the residual issues.

i=0
MAX=3
while [ $i -lt $MAX ]; do
  ./compile-and-check.sh && break
  ./apply-proposed-fix.sh   # via /academic-latex:author
  i=$((i+1))
done

Output to user

Verification result: pass | warn | fail
Pages: N
Fonts: all embedded | UNEMBEDDED: <list>
Refs/Cites: all resolved | UNDEFINED: <list>
Overfull boxes: <count> (largest: <Xpt>)
Visual issues found: <list with page numbers, or "none">
Reference diff (if requested): identical | differ on pages <list>
Iterations used: i / MAX
Residual issues: <if any>

When uncertain

If a visual issue isn't classifiable from the rendered image alone, flag it for the user — don't guess at the cause. For package-specific behaviour (e.g., why a microtype option produces a particular spacing), delegate to /academic-latex:docs-lookup.

Last verified

2026-05-09 — pdftocairo/pdftoppm/mutool man pages; diff-pdf README; ImageMagick compare reference.