flonat/claude-research/latex-health-check

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

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:

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:

1. Symlink integrity — verify all symlinks in skills/, agents/, rules/, hooks/ resolve
2. Shared .bib consistency — if multiple projects reference the same .bib file (e.g., via symlink), verify they're all pointing to the same version
3. Overleaf separation — scan every paper/ directory for forbidden file types (.py, .R, .csv, .ipynb, etc.)
4. 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`:

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

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

1. 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