flonat/flonat-research/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.

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

1. `paper/` is LaTeX-only — when extracting git revisions to temp dirs, write

temp copies under /tmp, never inside an Overleaf-synced paper/.

1. Clean up any git worktree / temp dirs you create.
2. 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.

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

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.

1. Note (don't dump) the trivial/formatting/move changes as a count.
2. 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