paper-compile skill

Paper Compile: LaTeX to Submission-Ready PDF

Compile the LaTeX paper and fix any issues: $ARGUMENTS

Constants

• COMPILER = latexmk — LaTeX build tool. Handles multi-pass compilation automatically.
• ENGINE = pdflatex — LaTeX engine. Options: pdflatex (default), xelatex (for CJK/custom fonts), lualatex.
• MAXCOMPILEATTEMPTS = 3 — Maximum attempts to fix errors and recompile.
• PAPERDIR = paper/** — Directory containing LaTeX source files.
• MAXPAGES — Page limit. ML conferences: main body to Conclusion end (excluding references & appendix). ICLR=9, NeurIPS=9, ICML=8. IEEE venues: references ARE included in page count.** IEEE journal ≈ 12-14 pages, IEEE conference ≈ 5-8 pages (all inclusive).

Workflow

Step 1: Verify Prerequisites

Check that the compilation environment is ready:

# Check LaTeX installation
which pdflatex && which latexmk && which bibtex

# If not installed, provide instructions:
# macOS: brew install --cask mactex-no-gui
# Ubuntu: sudo apt-get install texlive-full
# Server: conda install -c conda-forge texlive-core

Verify all required files exist:

# Must exist
ls $PAPER_DIR/main.tex

# Should exist
ls $PAPER_DIR/references.bib
ls $PAPER_DIR/sections/*.tex
ls $PAPER_DIR/figures/*.pdf 2>/dev/null || ls $PAPER_DIR/figures/*.png 2>/dev/null

Step 2: First Compilation Attempt

cd $PAPER_DIR

# Clean previous build artifacts
latexmk -C

# Full compilation (pdflatex + bibtex + pdflatex × 2)
latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex 2>&1 | tee compile.log

Step 3: Error Diagnosis and Auto-Fix

If compilation fails, read compile.log and fix common errors:

Missing packages:

! LaTeX Error: File `somepackage.sty' not found.

→ Install via tlmgr install somepackage or remove the \usepackage if unused.

Undefined references:

LaTeX Warning: Reference `fig:xyz' on page 3 undefined

→ Check \label{fig:xyz} exists in the correct figure environment.

Missing figures:

! LaTeX Error: File `figures/fig1.pdf' not found.

→ Check if the file exists with a different extension (.png vs .pdf). Update the \includegraphics path.

Citation undefined:

LaTeX Warning: Citation `smith2024' undefined

→ Add the missing entry to references.bib or fix the citation key.

[VERIFY] markers in text: → Search for [VERIFY] markers left by /paper-write. These indicate unverified citations or facts. Search for the correct information or flag to the user.

Overfull hbox:

Overfull \hbox (12.5pt too wide) in paragraph at lines 42--45

→ Minor: usually ignorable. If severe (>20pt), rephrase the text or adjust figure width.

BibTeX errors:

I was expecting a `,' or a `}'---line 15 of references.bib

→ Fix BibTeX syntax (missing comma, unmatched braces, special characters in title).

\crefname undefined for custom theorem types: → Ensure \crefname{assumption}{Assumption}{Assumptions} and similar are in the preamble after \newtheorem{assumption}.

Step 4: Iterative Fix Loop

for attempt in 1..MAX_COMPILE_ATTEMPTS:
    compile()
    if success:
        break
    parse_errors()
    auto_fix()

For each error:

1. Read the error message from compile.log
2. Locate the source file and line number
3. Apply the fix
4. Recompile

Stuck after 2 attempts? If Codex plugin is installed, invoke /codex:rescue — Codex can independently read the LaTeX source and compile.log to spot issues Claude missed (e.g., conflicting packages, encoding problems, subtle macro errors). If not installed, continue with Claude's own diagnosis.

Step 5: Post-Compilation Checks

After successful compilation, verify the output:

# Check PDF exists and has content
ls -la main.pdf
# Check page count
pdfinfo main.pdf | grep Pages

# macOS: open for visual inspection
# open main.pdf

Visual review (automated): If the compiled PDF exists, read it directly to check visual presentation:

• Figure quality: readable labels, legible text, distinguishable colors
• Layout: no orphaned section headers, no awkward page breaks
• Figures appear near their first text reference (not pages away)
• Tables: aligned columns, consistent decimal precision
• No overfull content visibly extending past margins

This is a quick visual scan, not a full review — the improvement loop does deeper visual review.

Automated checks:

• [ ] PDF file exists and is > 100KB (not empty/corrupt)
• [ ] Total page count is reasonable (MAX_PAGES + appendix + references)
• [ ] No "??" in the PDF (undefined references — grep the log)
• [ ] No "[?]" in the PDF (undefined citations — grep the log)
• [ ] Figures are rendered (not missing image placeholders)

# Check for undefined references
grep -c "LaTeX Warning.*undefined" compile.log

# Check for missing citations
grep -c "Citation.*undefined" compile.log

Step 6: Page Count Verification

CRITICAL: Verify paper fits within MAX_PAGES.

For ML conferences (ICLR/NeurIPS/ICML/CVPR/ACL/AAAI): Main body = first page through end of Conclusion section (not necessarily §5 — could be §6, §7, or §8 depending on structure). References and appendix are NOT counted.

For IEEE venues: The TOTAL page count (including references) must fit within the limit. There is no separate "main body" counting — everything up to and including the references counts.

Precise check using pdftotext:

# Extract text and find where Conclusion ends vs References begin
pdftotext main.pdf - | python3 -c "
import sys
text = sys.stdin.read()
pages = text.split('\f')
for i, page in enumerate(pages):
    if 'Ethics Statement' in page or 'Reproducibility' in page:
        print(f'Conclusion ends on page {i+1}')
    if any(w in page for w in ['References', 'Bibliography']):
        lines = [l for l in page.split('\n') if l.strip()]
        for l in lines[:3]:
            if 'References' in l or 'Bibliography' in l:
                print(f'References start on page {i+1}')
                break
"

If Conclusion ends mid-page and References start on the same page, the main body is that page number (e.g., if both are on page 9, main body = ~8.5 pages, which is fine for a 9-page limit since it leaves room for the References header).

If over limit:

• Identify which sections are longest
• Suggest specific cuts (move proofs to appendix, compress tables, tighten writing)
• Report: "Main body is X pages (limit: MAX_PAGES). Suggestion: move [specific content] to appendix."

Step 6.5: Stale File Detection

Check for orphaned section files not referenced by main.tex:

# Find all .tex files in sections/ and check which are \input'ed by main.tex
for f in paper/sections/*.tex; do
    base=$(basename "$f")
    if ! grep -q "$base" paper/main.tex; then
        echo "WARNING: $f is not referenced by main.tex — consider removing"
    fi
done