Latex

LaTeX Document Compilation

Default compilation skill for all LaTeX documents. Compiles with autonomous error detection and resolution (up to 5 iterations), runs a citation audit on clean builds, and produces a quality score.

When to Use

• Default method for all LaTeX compilation
• Any .tex file that should compile to PDF
• When compilation fails and you want automatic diagnosis and repair
• When you want a post-compilation citation audit

When NOT to Use

• Markdown documents — use plain markdown, not LaTeX
• Quick notes or drafts — LaTeX overhead not worth it
• Documents that don't need citations, equations, or precise formatting
• Documents with exotic custom classes that need manual debugging

Quality Scoring

Apply numeric quality scoring using the shared framework and skill-specific rubric:

• Framework: ../shared/quality-scoring.md — severity tiers, thresholds, verdict rules
• Rubric: references/quality-rubric.md — issue-to-deduction mappings for this skill

Start at 100, deduct per issue found, apply verdict. Include the Score Block in the final report.

Critical Rules

1. Build artifacts go to out/, PDF stays in the source directory. Use this skill's fail-closed canonical bundle at templates/build-config/.latexmkrc; do not hand-write an END { system(...) } copy block because it can mask latexmk's failure status and copy stale PDFs. For VS Code builds, use the bundled canonical recipe that explicitly loads %DIR%/.latexmkrc—-cd alone is insufficient.
2. NEVER write BibTeX entries from memory. Verify against authoritative metadata sources such as Crossref or the DOI resolver before writing. Use an installed literature-search workflow when one is configured.
3. Check document class before adding packages. Some classes load packages internally (e.g., elsarticle loads natbib — adding \usepackage{natbib} causes errors).
4. Maximum 5 fix iterations. If the document still has errors after 5 auto-fix cycles, stop and report the unresolved errors to the user.
5. Never silently swallow errors. Every fix must be reported: what was wrong, what was changed, and which file was edited.
6. Preserve user intent. Auto-fixes should be minimal and conservative. Add packages or overrides — never remove user content.
7. Citation audit requires clean compilation. Only run the \cite{} vs .bib cross-check after zero errors.
8. Validate new bibliography entries. The built-in citation audit checks key cross-references. When .bib entries were added or modified, also check DOI resolution, required fields, author formatting, and whether a preprint has a published version. If a dedicated bibliography validator is installed, use it for this extended check; otherwise perform and report the direct checks.

Protocol

Phase 1: Pre-flight

1. Locate the .tex file. Resolve the path (absolute or relative to CWD).
2. Identify the project directory — the folder containing the .tex file.
3. Ensure the canonical .latexmkrc exists in the project directory. Resolve templates/build-config/.latexmkrc relative to this installed skill and stop if the bundle is missing. Never recreate a partial version from memory. Compare an existing file byte-for-byte with the bundled canonical; do not overwrite divergence blindly. Move project-specific bibliography paths or custom dependencies into .latexmkrc.local; move engine selection into a % !TEX program = ... driver comment. Replacing a divergent file remains an explicit migration.
4. Create out/ directory if it doesn't exist: mkdir -p <project-dir>/out.
5. Identify the .bib file(s) referenced in the document (scan for \bibliography{}, \addbibresource{}, or \bibinput{}). Note their paths for Phase 5.

Phase 2: Compile-Fix Loop

Run up to 5 iterations. Each iteration:

Step 2a — Compile

cd <project-dir> && latexmk -interaction=nonstopmode <filename>.tex 2>&1

Capture the full output. The log file will be at out/<filename>.log.

Step 2b — Read the log

Read out/<filename>.log in full. Parse for errors and warnings.

Step 2c — Classify errors

Check the log against the known error patterns below. If an error matches, apply the fix and go to Step 2a. If no known pattern matches, record the error as unresolved and stop the loop.

Same-error circuit breaker. Independent of the 5-iteration cap: if the same error (same line family, same pattern signature) survives 3 consecutive fix attempts, stop the loop early. Continued attempts on a stuck error compound damage rather than resolve it. Report what was tried, quote the log line, and ask the user how to proceed. A common signature: Illegal parameter number jumping between line numbers as you edit — that is the diagnostic for a parameterized TikZ style defined inside a Beamer frame; see skills/shared/tikz-rules.md Rule 11.

Known Error Patterns & Auto-Fixes

Check the log against these patterns. Full fix instructions: references/known-errors.md

If an error matches, read the full fix from the reference and apply it. If no pattern matches, record as unresolved and stop the loop.

2.4 PDF backup (paper directories only)

Only run if the compile-fix loop above ended with a successful compilation (PDF exists).

If the .tex file is inside a paper-{venue}/paper/ structure (where paper/ is a symlink to Overleaf):

1. Identify the paper wrapper — the parent of the paper/ symlink (e.g., paper-jbdm/).
2. Create the backup directory: mkdir -p <paper-wrapper>/backup
3. Copy the PDF:

   cp <paper-wrapper>/paper/<filename>.pdf <paper-wrapper>/backup/<wrapper-name>_vcurrent.pdf

Detection logic:

• The project directory containing the .tex file is a symlink named paper.
• Its parent directory name starts with paper-.
• If either condition is false, skip this sub-step silently.

Phase 3: Final Report

After the loop ends (either clean compilation or max iterations reached), report:

Compilation Status

How to extract page count

grep -o "Output written on .* ([0-9]* page" out/<filename>.log | grep -o "[0-9]* page"

How to count warnings and boxes

Warnings and typographic boxes are separate — box messages are not Warning-tagged, so a single Warning grep misses every overfull/underfull box. Report both, using the recipes in ../shared/overfull-boxes.md:

# LaTeX/package warnings (refs, fonts, packages)
grep -c "Warning" out/<filename>.log
# Overfull/underfull boxes (the thing the Warning grep cannot see)
grep -cE 'Overfull \\[hv]box \([0-9.]+pt too (wide|high)\)' out/<filename>.log
grep -cE 'Underfull \\[hv]box \(badness [0-9]+\)' out/<filename>.log

Box report (typographic quality)

Extract the top offenders by overflow magnitude and report each box ≥ 1 pt with its location, width, and a remediation tier per the severity gradient + ladder in ../shared/overfull-boxes.md:

awk -F'[()]' '/Overfull \\[hv]box/ {
    split($2, a, "pt"); w = a[1] + 0;
    loc = $0; sub(/.*too (wide|high)\) */, "", loc);
    printf "%7.1f pt  %s\n", w, loc
}' out/<filename>.log | sort -rn | head -20

Report only — do not silently reword prose to close a box (rules/manuscript-edit-budget.md). The only safe auto-fix is inserting \usepackage{microtype} when genuinely absent.

Breadcrumb: Append to .planning/state.md (if exists) or .context/current-focus.md:

### [latex] Compilation complete [YYYY-MM-DD HH:MM]
- **Done:** [Clean/Errors remaining, N iterations, N pages, N fixes applied]
- **Outputs:** [PDF at <path>]
- **Next:** [Citation audit (if clean) or manual error resolution]

Phase 4: Visual-Fragility Source Lint (clean builds only)

Only run if Phase 2 ended with zero errors. Sits between the final report (Phase 3) and the citation audit (Phase 5). Catches LaTeX source patterns that compile clean but produce visually fragile output — the failure class the title-page incident (2026-06-19) exposed.

Full detector catalogue with regex signatures, severity tiers, remediation, and false-positive caveats: references/source-pathologies.md.

What to run

1. Nine grep-based source-pathology detectors against main.tex plus any \input/\include'd files:

   #	Pattern	Tier
   1	Spacing hacks fighting global spacing (\onehalfspacing + local \\[-Xcm] / \vspace{-…})	Major
   2	Manual vertical-rhythm surgery (repeated \vspace/\vskip/\pagebreak in body)	Moderate–Major
   3	Line breaks as layout engine (\\ / \newline / \linebreak inside \section/\caption)	Moderate–Major
   4	Forced-float carpet bombing ([H]/[!h] pinning, \FloatBarrier overuse)	Moderate
   5	Shrink-to-fit tables/figures (\resizebox{\textwidth}{!}{…}, \adjustbox{width=\textwidth})	Major
   6	Tiny-table typography hacks (\scriptsize/\tiny in tables; negative \tabcolsep; \arraystretch<0.9)	Moderate–Major
   7	Absolute / overlap positioning (\raisebox, \makebox[0pt], \llap, \rlap, \smash, \hspace*) outside math	Major
   8	Fixed-width layout assumptions (p{Xcm}, \begin{minipage}{Xcm}, \parbox{Xcm})	Moderate
   9	Label-before-caption inside floats (\label{…} precedes \caption{…} in a figure/table block)	Major

2. chktex if installed: chktex -q -n8 -n44 main.tex 2>&1 | grep -v "^$". Advisory only — collect warnings; deduct -1 each, capped at -10. Skip if chktex not on PATH.

3. latexindent -k if installed: latexindent -k main.tex 2>&1; echo "Exit: $?". Source-cleanliness smoke test. Non-zero exit → -3 once. Skip if latexindent not on PATH.