LaTeX Health Check: Self-Healing Build Agent

Compile all LaTeX projects, auto-fix known errors iteratively, and verify cross-project consistency (symlinks, shared bibliographies, Overleaf separation).

When to Use

Periodically (weekly) to catch build rot before it becomes debugging sessions
After major infrastructure changes (template updates, symlink reorganisation)
Before submission season to verify all papers compile cleanly
When the user says "check my LaTeX", "build health", "compile everything"

Modes

| Mode | Trigger | What it does | |------|---------|-------------| | Single project | Path argument | Compile + fix + verify one project | | All projects | all argument | Discover and compile every LaTeX project | | Quick | quick argument | Compile only, no fixes, report errors |

Phase 1: Discover LaTeX Projects

Find all directories containing a \documentclass in a .tex file:

Search locations in this order, checking that each exists:

an explicit path argument;
the current project;
project roots declared by the current repository or client guidance;
~/Projects/ as a portable fallback for all mode.

For each discovered project, record:

Project name (directory name)
Main .tex file path
Whether it has a .latexmkrc
Whether it has an out/ directory
Whether it's inside a paper/ subdirectory (Overleaf-linked)

Phase 2: Build Loop (per project)

For each project:

2a. Pre-flight

Resolve the byte-identical templates/build-config/.latexmkrc bundle from the installed latex skill; stop if it is unavailable.
If .latexmkrc is missing, copy the resolved canonical verbatim. If it exists, compare it byte-for-byte; report divergence and do not overwrite it without explicit migration approval.
Allow .latexmkrc.local for project-specific paths, dependencies, $bibtex_use, $clean_ext, or @default_files, but flag any $pdf_mode assignment.
Create out/ directory if missing

2b. Compile

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

Engine selection: Do NOT hardcode -pdf. The canonical recursively infers pdfLaTeX, XeLaTeX, or LuaLaTeX from the requested driver and local dependencies. Passing -pdf overrides this and breaks Unicode-engine projects. Let latexmk read .latexmkrc.

2c. Parse log

Extract from out/*.log:

Error count (lines starting with !)
LaTeX/package warning count (Warning-tagged lines)
Overfull/underfull box count — use the detection recipes in ../shared/overfull-boxes.md, NOT a Warning grep (box lines carry no Warning token)
Undefined citation count
Missing package count

2d. Auto-fix (up to 3 iterations)

For each error, apply the known fix from the database:

| Error pattern | Fix | |--------------|-----| | Missing package X | Add \usepackage{X} — but NEVER try xltabular or ltablex (use longtable instead) | | Undefined citation key | Check .bib file exists and is referenced; check for typos via edit distance | | Overfull/underfull box | Flag location + width per ../shared/overfull-boxes.md — do NOT auto-fix prose (only safe auto-fix is adding microtype when absent) | | tcolorbox = or , in title | Wrap title in braces: title={...} | | Font encoding warning | Add \usepackage[T1]{fontenc} if missing | | Missing \begin{document} | Check for corrupted preamble | | Broken symlink in \input{} or \includegraphics{} | Find the target and report | | Build artifacts in source dir | Flag — offer to move to out/ |

After each fix, recompile. Max 3 iterations per project.

Why 3 iterations (not 5)? latex runs up to 5 iterations on a single project with deep error analysis. This skill trades depth for breadth — 3 iterations is enough to catch the common fleet-wide issues (missing packages, broken symlinks, stale cache) without spending excessive time on any one project. If a project still has errors after 3 iterations, mark it as ERROR and recommend running latex on it directly for deeper diagnosis.

2e. Record result

{
  "project": "project-name",
  "path": "/full/path",
  "status": "OK | FIXED | ERROR",
  "errors_initial": 3,
  "errors_final": 0,
  "fixes_applied": ["added fontenc", "fixed tcolorbox title"],
  "warnings": 2,
  "undefined_citations": 0
}

Phase 3: Cross-Project Checks

After all projects are compiled:

Symlink integrity — verify all symlinks in skills/, agents/, rules/, hooks/ resolve
Shared .bib consistency — if multiple projects reference the same .bib file (e.g., via symlink), verify they're all pointing to the same version
Overleaf separation — scan every paper/ directory for forbidden file types (.py, .R, .csv, .ipynb, etc.)
Template consistency — check if projects using the working paper template have diverged from the current template version

Phase 4: Report

Generate a summary report:

LaTeX Health Check — YYYY-MM-DD

Projects scanned:  N
Compiled OK:       N (list)
Fixed and OK:      N (list + fixes applied)
Still broken:      N (list + remaining errors)
Skipped:           N (list + reason)

Cross-project issues:
  Broken symlinks:        N
  Overleaf violations:    N
  Template drift:         N

Warnings (not auto-fixed):
  Overfull hboxes:        N across M projects
  Underfull hboxes:       N across M projects

Print to stdout. If --save flag or 10+ projects scanned, also write to log/latex-health/YYYY-MM-DD.md.

4.1 Output verification (before commit)

When writing the report file, emit an outputs manifest and run the shared verifier per _shared/verify-outputs.md:

Write manifest to <project>/.claude/state/outputs-manifest-<UTC-timestamp>.json listing every file written this invocation, paths relative to the project root.

Run:

uv run python "<skills-root>/_shared/verify_outputs.py" \
    --manifest "$MANIFEST" \
    --project-root "$PROJECT_ROOT"

If the verifier exits non-zero, do not commit. Surface the missing-files list and stop.

Closes the "hallucinated outputs" failure class (commit b2cff75, 2026-04-18). Skip this sub-step entirely if --save was not passed and no log file was written.

What This Skill Does NOT Do

Does NOT fix overfull/underfull boxes (requires human judgment on rewording)
Does NOT modify paper content (only build configuration and missing packages)
Does NOT push to git (compilation fixes should be reviewed first)
Does NOT touch Overleaf-synced files without permission (per overleaf-separation rule)

Cross-References

| Skill | Relationship | |-------|-------------| | latex | Single-project deep fix (5 iterations). This skill runs a lighter version (3 iterations) at fleet scale. For ERROR projects, recommend running latex directly. | | latex | Canonical .latexmkrc resolution, migration rules, and single-project deep compilation. | | audit-project-research | Checks project structure (directories, files). This skill checks build health. | | bib-validate | Validates bibliography entries. This skill checks if citations compile. | | latex-template | Checks preamble alignment with the working paper template. Complementary: run after health-check to ensure preamble consistency. |