latex-diff

name	latex-diff
description	Compare two LaTeX files, project directories, or Git revisions and produce human-readable plus machine-readable severity-graded semantic changes. Use when determining what changed between manuscript versions or preparing a revision audit bundle. Not for proofreading one version; use $proofread.
allowed-tools	Bash(latexdiff-agent:*), Bash(git show:*), Bash(git diff:*), Bash(git worktree:*), Bash(git log:*), Bash(mktemp*), Bash(mkdir*), Bash(ls*), Bash(rm*), Read, Glob, Grep
argument-hint	[old] [new] (files, dirs, or git revisions)

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

Input form	How to run
Two files	latexdiff-agent OLD.tex NEW.tex …
Two project dirs (multi-file, \input/\include-aware)	latexdiff-agent OLD_DIR/ NEW_DIR/ …
Two git revisions of one file	extract each, then diff (below)
Two git revisions of a whole project	git worktree each, then diff dirs (below)

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.

2. Run the diff

Get both views in one pass — the human summary to read aloud, and the semantic-only JSON to reason over:

latexdiff-agent <OLD> <NEW> --summary -                 # human view
latexdiff-agent <OLD> <NEW> --compact --semantic-only   # the changes that matter

Useful filters (compose freely): --min-severity high, --type citation, --section Methods, --file sections/intro.tex.

3. Persist a requested diff bundle

If the user asks to generate, create, save, or deliver a diff inside a research project, resolve the project root and paper scope, then create the canonical destination. A conversational request to explain changes without saving files may remain stdout-only.

STAMP=$(date '+%Y-%m-%d-%H%M')
OUT="<project-root>/reviews/<scope>/<check>"
BASE="$OUT/$STAMP"
mkdir -p "$OUT"
latexdiff-agent <OLD> <NEW> --summary "$BASE.md"
latexdiff-agent <OLD> <NEW> --compact --semantic-only --json "$BASE.changes.json"

Add same-stem companions only when useful:

latexdiff-agent <OLD> <NEW> --json "$BASE.full.json"
latexdiff-agent <OLD> <NEW> --latexdiff "$BASE.diff.tex"
git diff <OLD> <NEW> > "$BASE.source.patch"  # source-level comparison only

Compile .diff.tex through the latex workflow when the user requests a visual diff; keep intermediate build artifacts in out/ and copy only the final .diff.pdf beside the bundle. Record the two stable comparison inputs in the Markdown report; never expose disposable /tmp paths as the authoritative baseline/current identifiers.

4. Report

1. Lead with the summary line: total changes, semantic-impact count, impact score.
2. List the semantic-impact changes grouped by section, each with its file:line, type, and severity. These are the ones worth attention.
3. Note (don't dump) the trivial/formatting/move changes as a count.
4. If the user wanted a changelog or response-letter "summary of changes", phrase the semantic changes as prose bullets — but do not edit the manuscript (rules/manuscript-edit-budget.md); hand the bullets back for them to place.

Cross-References

Skill	Relationship
latex	Compiles documents; this skill compares versions of them
review-artefact-routing	Governs the scoped producer route and same-stem companion contract
strategic-revision --external	Consumes this as evidence for the R&R "summary of changes"; it does not turn internal findings into venue claims
preprint	Consumes this for a vN→vN+1 changelog on version bump
paper-critic / referee2-reviewer	Can take --semantic-only JSON to focus a re-review on what changed
packages/latex-diff/README.md	Full CLI flags, schema, and design notes