LaTeX Documents skill for Codex

Done well means: the document builds from a clean checkout with one command, produces no undefined references or citations, no unexplained overfull boxes, and its source is split so collaborators can edit chapters without merge pain.

Before changing anything

1. Find the root file (the one with \documentclass) and the build entry point: a .latexmkrc, Makefile, CI workflow, or AGENTS.md note. Use it rather than inventing one.
2. Identify the engine and bibliography toolchain from the preamble: fontspec means LuaLaTeX/XeLaTeX; biblatex usually means biber; \bibliographystyle plus \bibliography{} means BibTeX.
3. Check TeX is installed: latexmk -v, lualatex --version. Installing TeX Live or missing packages (tlmgr install <pkg>) needs network and a lot of disk; in a sandbox, ask for approval or use the project’s Docker image (texlive/texlive).
4. If a journal or university template is involved, use their class file unmodified and put your additions in the preamble of your own file.

Engine choice

Need	Engine
Journal/arXiv submission, classic templates, fastest builds	pdfLaTeX
System/OpenType fonts, Unicode text, modern default for new documents	LuaLaTeX
Existing XeLaTeX project, or specific CJK setups	XeLaTeX

arXiv compiles with pdfLaTeX by default; check its current TeX Live year before relying on very new packages.

Project layout

paper/
├── main.tex            # preamble + \input of sections, nothing else
├── .latexmkrc
├── sections/           # intro.tex, method.tex, results.tex ...
├── figures/            # PDF/PNG figures; vector PDF for plots
├── tables/             # generated .tex tables (from scripts)
└── refs.bib

# .latexmkrc
$pdf_mode = 4;                 # 1 pdflatex, 4 lualatex, 5 xelatex
$out_dir = 'build';
@default_files = ('main.tex');
$bibtex_use = 2;               # run biber/bibtex when needed, clean .bbl with -c
set_tex_cmds('-interaction=nonstopmode -halt-on-error -file-line-error -synctex=1 %O %S');

latexmk                # builds main.tex into build/ per .latexmkrc
latexmk -pvc           # rebuild on save
latexmk -c             # remove auxiliary files (keep the PDF)

A preamble that avoids common conflicts

\documentclass[11pt,a4paper]{article}
\usepackage{fontspec}                   % LuaLaTeX/XeLaTeX; for pdfLaTeX use \usepackage[T1]{fontenc} + lmodern
\setmainfont{Libertinus Serif}
\usepackage{microtype}
\usepackage{amsmath,amssymb}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{siunitx}
\usepackage[style=authoryear,backend=biber]{biblatex}
\addbibresource{refs.bib}
\usepackage[hidelinks]{hyperref}        % load late
\usepackage[capitalise,noabbrev]{cleveref}   % after hyperref
\graphicspath{{figures/}}

Order matters: hyperref near the end, cleveref after it. Do not load both natbib and biblatex, or subfigure with subcaption.

Content patterns

\begin{figure}[tbp]
  \centering
  \includegraphics[width=\linewidth]{latency-p95.pdf}
  \caption{p95 latency by region after the cache change.}
  \label{fig:latency}                 % label after caption, or references point to the section
\end{figure}

\begin{table}[tbp]
  \centering
  \caption{Throughput per configuration.}
  \label{tab:throughput}
  \begin{tabular}{l S[table-format=4.1] S[table-format=2.2]}
    \toprule
    Config & {Req/s} & {Error \%} \\
    \midrule
    Baseline & 1204.5 & 0.41 \\
    Cached   & 1890.2 & 0.12 \\
    \bottomrule
  \end{tabular}
\end{table}

As \cref{fig:latency} shows, the change halves tail latency \parencite{dean2013tail}.

• Tables generated from data: write them from code into tables/*.tex (pandas DataFrame.to_latex or a small template) and \input them; never retype numbers.
• Use booktabs rules, no vertical lines; align numbers on the decimal point with siunitx.
• Plots: export vector PDF (matplotlib savefig("x.pdf")), sized to the final width so fonts are not scaled down.

Bibliography

@article{dean2013tail,
  author  = {Dean, Jeffrey and Barroso, Luiz Andr{\'e}},
  title   = {The Tail at Scale},
  journal = {Communications of the ACM},
  volume  = {56},
  number  = {2},
  pages   = {74--80},
  year    = {2013},
  doi     = {10.1145/2408776.2408794},
}

• Protect capitalisation that must survive styles: title = {Scaling {BERT} on {GPUs}}.
• One key format (authorYYYYword), no duplicates: biber --tool --validate-datamodel refs.bib reports problems.
• biblatex needs biber; BibTeX styles (.bst) need bibtex. A mismatch shows as “Citation undefined” on every key.
• For arXiv with biblatex, upload the generated .bbl; it must come from a biber version matching arXiv’s biblatex, otherwise switch that submission to BibTeX.

Reading a failed build

Read the log from the first error, not the last line. With -file-line-error, errors look like ./sections/method.tex:42: Undefined control sequence.

Message	Usual cause	Fix
Undefined control sequence	Typo or missing package	Check the macro on that line; add the package
Missing $ inserted	_, ^ or math outside math mode	Escape \_, wrap math in $...$
File 'x.sty' not found	Package not installed	tlmgr install x (network) or use the TeX Live Docker image
Citation 'k' undefined	Key missing in .bib, or bib tool not run	Check key spelling; run full latexmk
Reference 'fig:x' undefined	Label typo or label before caption	Fix label; rebuild
Overfull \hbox (12.3pt too wide)	Long word/URL, wide table or image	\url{}, \linewidth, rephrase, \sloppy locally as last resort
Option clash for package x	Package loaded twice with different options	Load once; pass options via \PassOptionsToPackage before the class loads it
Dimension too large	Plot coordinates huge (pgfplots)	Rescale data or use fpu

Stuck after edits that should work: latexmk -C (removes stale aux files), then rebuild.

CI

# .github/workflows/latex.yml
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    container: texlive/texlive:latest
    steps:
      - uses: actions/checkout@v4
      - run: latexmk
      - run: "! grep -E 'undefined|Rerun to get' build/main.log"
      - uses: actions/upload-artifact@v4
        with: { name: paper, path: build/main.pdf }

Pin the image tag (e.g. a TeX Live year tag) when a submission must be reproducible.

Verification

latexmk -C && latexmk                                   # clean build succeeds
grep -nE "LaTeX Warning: (Reference|Citation).*undefined" build/main.log   # expect nothing
grep -c "Overfull" build/main.log                        # review each one
pdffonts build/main.pdf                                  # all fonts embedded (journals require it)

Open the PDF and check: every \cref resolves to the right number, the bibliography lists only cited works, figures appear near their first mention.

Hand-over

**Build:** `latexmk` (LuaLaTeX via .latexmkrc, output build/main.pdf, 14 pages)
**Fixed:** cleveref loaded before hyperref; 3 labels placed before captions; missing siunitx
**Bibliography:** biblatex + biber, 42 entries, 0 undefined citations
**Remaining:** 1 overfull box in tables/ablation.tex (2.1pt) - acceptable or shorten header