Latex Diff

LaTeX Diff

Compare two versions of a LaTeX document and report what actually changed — text, equations, citations, labels/refs, section titles, macros, environments, file add/remove, and moves — each graded by severity. Wraps the latexdiff-agent CLI (packages/latex-diff). Member of the latex-* source/build family.

When to Use

• "What changed between these two versions of the paper?"
• Building an R&R "summary of changes" or a preprint vN→vN+1 changelog
• Focusing a re-review on the changes that matter (semantic-impact only)
• Sanity-checking a co-author's edits before merging

When NOT to Use

• Compiling a document → latex
• Prose quality / proofreading → proofread
• A raw line diff is enough → git diff (this skill is LaTeX-aware: it knows a changed \cite key from a reflowed paragraph)

What it produces

Two views from the same canonical diff:

1. Human summary — grouped by file and section, every line carrying a change id, a severity badge, and a file:line location.
2. Machine-readable JSON — severity-graded ChangeRecords. semantic_impact: true flags the changes a reviewer should actually read.

For a persistent run inside a research project, these are the mandatory core files. Use one timestamp-only basename for the whole run:

reviews/<scope>/<check>/<YYYY-MM-DD-HHMM>.md
reviews/<scope>/<check>/<YYYY-MM-DD-HHMM>.changes.json

Here and below, <check> is this skill's frontmatter name.

Co-locate applicable typed companions with the same basename:

• .full.json — unfiltered machine-readable inventory
• .changes.md — full or raw human-readable inventory when the primary report is a shorter curated summary
• .diff.tex and .diff.pdf — rendered manuscript comparison
• .source.patch — exact source patch for source-only changes such as citation rekeys

The core pair is stable; companions vary with the comparison. Do not replace the core pair with a PDF, patch, or run-specific directory.

Severity ladder: trivial < low < medium < high < critical. Change types: formatting_only, text, equation, citation, label_ref, environment, section_title, macro_definition, file_add, file_remove, move, other.

Full flag reference: packages/latex-diff/README.md.

Critical rules

1. Read-only. This skill never edits the paper. It reports; the human (or a downstream skill) decides what to do.
2. paper/ is LaTeX-only — when extracting git revisions to temp dirs, write temp copies under /tmp, never inside an Overleaf-synced paper/.
3. Clean up any git worktree / temp dirs you create.
4. Route generated artifacts by provenance. In a research project, persist them under reviews/<scope>/<check>/, where <scope> is the target paper slug or _project and <check> is this skill's frontmatter name. Never place generated diff output under correspondence/; genuine reviewer/editor/co-author material may be an input, but it remains external correspondence.
5. Use a flat, same-stem bundle. Put files directly in the producer directory with a YYYY-MM-DD-HHMM basename. Do not create a timestamped run subdirectory and do not use README.md, summary.md, or bespoke basenames.

Protocol

1. Resolve the two inputs

Single file across revisions:

git show <REV_OLD>:<path/to/main.tex> > /tmp/ld-old.tex
git show <REV_NEW>:<path/to/main.tex> > /tmp/ld-new.tex   # omit for working tree
latexdiff-agent /tmp/ld-old.tex /tmp/ld-new.tex --summary -

Whole project across revisions (multi-file):

git worktree add /tmp/ld-old <REV_OLD>
git worktree add /tmp/ld-new <REV_NEW>
latexdiff-agent /tmp/ld-old/<paper-dir> /tmp/ld-new/<paper-dir> --summary - --compact --semantic-only
git worktree remove /tmp/ld-old && git worktree remove /tmp/ld-new

Resolve revisions with git log --oneline -- <path> when the user names a round ("since submission", "v1") rather than a SHA. If ambiguous, ask.