review-diff

---
name: review-diff
description: Review only the modified parts of a git-versioned document for AI slop and rule violations. Use when the user has uncommitted edits or a feature branch and wants to audit only what they changed, not the whole draft. Triggers on prompts such as "check my edits", "review what I just changed", "audit this branch's prose", or `/ai-slop:review-diff`. Uses the same layered rules as `/ai-slop:review` (general by default; `--scientific` and LaTeX layers as detected; `--ste` for the Simplified Technical English layer), scoped to the diff. Writes a structured Markdown report that revise mode can apply.
license: CC-BY-4.0
metadata:
  version: "2026-10_rev7"
  homepage: https://github.com/se-uhd/ai-slop-skill
---

# AI Slop Review: Diff Mode

This skill reviews only the lines that changed in a git-versioned document. It runs `git diff <base>` (default base: `HEAD`), restricts rule and trope checks to lines added or modified in `.tex`, `.md`, and `.txt` files, applies the LaTeX layers to the `.tex` changes and the general layer to the rest, and writes the same `ai-slop-report.md` schema as `/ai-slop:review` so `/ai-slop:revise` can apply the suggestions unchanged.

**Audience and tone.** The default user is an author who is iterating on a draft and wants a quick pass over their latest edits before committing or sharing. Frame findings as suggestions, not violations.

## Client and paths

This workflow works in Claude Code and Codex. Resolve `<skill-dir>` to the absolute directory containing this `SKILL.md`, using the skill path supplied by the client. Substitute that directory in every command below and keep the script path quoted. Resolve `../../shared/` and other bundled paths relative to that directory, while keeping the working directory at the user's project. No client-specific environment variable is required.

In Claude Code, invoke `/ai-slop:review-diff`. In Codex, select the `ai-slop:review-diff` skill through `/skills` or a `$` mention. References to other `/ai-slop:` commands below mean the corresponding sibling skill in either client.

## When to use

Invoke this skill when the user:

1. Has a paper repo with uncommitted edits (or a feature branch) and asks to check just the changes, for example, "review my edits before I commit", "audit what I just changed", "check this branch's prose".
2. Runs `/ai-slop:review-diff` with or without a base ref.

Do not invoke for a full-paper pass (use `/ai-slop:review`) or when the working directory is not a git repository (tell the user and suggest `/ai-slop:review` instead).

## Inputs

The skill auto-detects the paper and the diff in the current working directory.

**Base ref.** Defaults to `HEAD` (so the review covers staged + unstaged changes in the working tree). The user may pass any git ref as a positional argument:

- No argument -> `git diff HEAD` (uncommitted changes vs the last commit).
- A branch or commit-ish (e.g., `main`, `abc1234`) -> `git diff <ref>` (working tree vs that ref).

If the working directory is not inside a git repository (`git rev-parse --is-inside-work-tree` returns non-zero), stop and tell the user, e.g., "Not a git repository; use `/ai-slop:review` for a full-paper review."

**Paper detection.** Run `python3 "<skill-dir>/../../scripts/find_latex_root.py"` to learn whether a LaTeX root exists, which step 10 needs for following `\input` / `\include`. Exit 0 means that the printed path is the root. Exit 2 means that multiple candidates were printed, so ask the user. Exit 1 means no `.tex` root, which is not an error in diff mode. Which layers apply is decided per changed file in step 6, so a code repository with one paper under a subdirectory still gets its Markdown changes reviewed. PDF input is never reviewed in diff mode because no diff is available for it.

**Trope catalog override.** `--tropes=<path>` (repeatable) replaces the catalog download with one or more user-supplied files. Contents are concatenated in the order given. When `--tropes` is not passed (the common case), the catalog is fetched live (see step 7).

**STE mode.** `--ste` adds the Simplified Technical English layer to every changed file, as in `/ai-slop:review`.

## Workflow

1. **Verify git context.** Run `git rev-parse --is-inside-work-tree`. If not in a git repo, stop with the message above. Otherwise capture the repo root for later path resolution.

2. **Resolve inputs.** Auto-detect the LaTeX root, if any (see Paper detection). Parse the base ref (default `HEAD`) and any `--tropes=<path>` arguments (repeatable) from the user's message.

3. **Compute the diff.** Run `git diff --unified=0 <base> -- '*.tex' '*.md' '*.txt'` to list changed lines. Parse the unified-diff hunk headers (`@@ -<old_start>,<old_count> +<new_start>,<new_count> @@`) to extract per-file line ranges of added or modified lines in the new tree (the working-tree side). Track these as the **changed-line set** per file. If no matching files changed, write an empty report (Summary: "No changes since `<base>`."), print it, and stop.

4. **Expand to paragraph context.** For each changed-line range, expand outward in the new file to the nearest preceding and following blank line so the changed prose is reviewed in its full paragraph. Record both:
   - the **changed lines** (used to scope what counts as a finding), and
   - the **surrounding paragraph** (used as context so multi-line tropes or sentence-length checks have enough text to operate on).

5. **Identify sections.** For each changed paragraph, walk backward in the new file to the nearest preceding `\section{}` or `\subsection{}` (for Markdown, the nearest preceding `#` / `##` heading) to map the paragraph to its section. The section mapping selects the section-aware rules (e.g., verb tense, threats-to-validity specificity), which apply only when the scientific layer is in scope.

6. **Determine which rule layers to load.** Same layers as `/ai-slop:review` under `../../shared/`. Decide per changed file. Run `python3 "<skill-dir>/../../scripts/detect_scope.py" <file>` on each. A `latex` file (any `.tex`) gets the general, scientific, and LaTeX layers. A `general` file gets `rules-general.md`, plus `rules-scientific.md` when `--scientific` was passed (a non-LaTeX research manuscript). With `--ste`, every changed file also gets `rules-ste.md`, which sets the limit wherever it and the general layer disagree (`T.precedence`). Read each selected layer file. Each adds its own rules and self-check section. Read the applicable project `GLOSSARY.md`, or a glossary named by project instructions, before checking terminology, preserving its concept boundaries, accepted variants, and scope exceptions. Treat synonyms mentioned as retired vocabulary in the glossary as reference material, not as violations in that file. The `Rule` field of a finding carries the rule name as written in the layer, followed by its key in parentheses, as in `Semicolons (G.semicolons)`. A catalog trope carries its name and its catalog status, as in `Negative parallelism (tropes.fyi, consistent)`.

7. **Load the AI trope catalog.** If `--tropes=<path>` was passed (one or more times), read each named file and concatenate them in the order given. Otherwise run `python3 "<skill-dir>/../../scripts/fetch_tropes.py"` and read its stdout. tropes.fyi is the only source and there is no bundled fallback, so the script exits 1 with an empty stdout when it cannot fetch the catalog. Stop there and tell the user that the catalog could not be fetched, naming `--tropes=<path>` as the way to review against a local copy.

8. **Per-paragraph pass.** For each changed paragraph, scan the prose against the rules and the trope catalog. Apply `G.context-first` before reporting a candidate: read the surrounding context, identify the function of the sentence, and require a concrete benefit from the proposed edit. Word matches and counts are not findings by themselves. Preserve purpose, distinctions, logical relations, scope, emphasis, and voice. Read adjacent paragraphs as context for `G.connected-prose`, and check that a revision preserves the development of the argument. A finding is in scope only if at least one line of the offending quote falls inside the changed-line set. A pre-existing violation on an unchanged line is out of scope, even when adjacent to a change. For each in-scope violation, record:
   - The rule name with its key, as in `Semicolons (G.semicolons)`, or the trope name with its catalog status, as in `Negative parallelism (tropes.fyi, consistent)`.
   - The location (`file:line` in the new file).
   - A short verbatim quote of the offending text, with enough surrounding context to be unique within the paper.
   - A concrete suggested replacement.
   - A **Reason** explaining the problem in context and the benefit of the replacement, or naming the explicit convention being corrected.

   In STE mode, list a changed sentence that an STE rewrite would weaken under **Items requiring author judgment** instead of reporting it, as `/ai-slop:review` step 4 does.

9. **Cross-cutting metrics, scoped to the diff.** Compute on changed lines only:
   - Dash count and locations in changed lines. Run `python3 "<skill-dir>/../../scripts/scan_glyphs.py"` over the changed files and keep the rows inside the changed-line set, as `/ai-slop:review` step 5 does.
   - Reference candidates on changed lines, from `python3 "<skill-dir>/../../scripts/scan_reference.py"` over the changed files, filtered the same way and tested per the **Reference** rules.
   - Repeated sentences on changed lines, from `python3 "<skill-dir>/../../scripts/scan_repeats.py"` over the changed files. Keep a row when its sentence (the later occurrence) is on a changed line, and test it per **Refer back instead of repeating** (`G.refer-back`) as `/ai-slop:review` step 5 does. A changed sentence that an unchanged one repeats later is out of scope.
   - Restricted-word occurrences in changed lines.
   - Verb-tense compliance for changed paragraphs (against the section table in the scientific layer, and only when that layer is in scope).
   - American-vs-British spelling in changed lines.
   - "Significant" audit on changed lines.
   - STE sentence candidates on changed lines (STE mode only), from `python3 "<skill-dir>/../../scripts/scan_sentences.py"` over the changed files. A `long-sentence` or `uniform-run` row names the line on which its first sentence starts, and a `passive` or `nominalization` row names the line of the matched words. Read the whole sentence and keep the row when any of its lines is in the changed-line set. Keep a `uniform-run` row when the run includes a changed line. Test the rows as `/ai-slop:review` step 5 does.

   Skip metrics that need full-paper context (e.g., em-dash *density* per page, sentence-length variance over runs of three sentences spanning untouched prose, restricted-word density per paragraph when the diff touched only a fraction of the paragraph). Note the scoping in the report Summary.

   Density needs full-paper context, but a single mark that is the wrong choice does not. On a changed line, treat a semicolon joining two independent clauses that a period would separate (especially when the second opens with we, it, this, they, or these), an em-dash standing in for a period, or a colon used as a generic mid-sentence pause as a per-section finding, with the corrected punctuation as the suggested revision.

10. **Citations and BibTeX, scoped to the diff.** On changed lines, scan for newly added or modified `\cite{}` calls. Apply the same checks as `/ai-slop:review` step 6 (citation clusters with three or more entries lacking per-work explanation; missing grounding comments, with `% GROUNDING <key>:` counted as grounded like `% GROUNDING:`; and spelled-out author names that should use `\citeauthor{}`). For BibTeX field checks scoped to newly cited keys, identify the `.bib` files via `\bibliography{...}` / `\addbibresource{...}` directives, run `python3 "<skill-dir>/../../scripts/check_bib_fields.py" <bibfiles>`, and report only entries cited in newly added `\cite{}` calls. Do not flag pre-existing citations that the diff did not touch. Standard BibTeX semantics apply (no `crossref` inheritance), so sanity-check flagged entries. Always list changed `\cite{}` calls that lack a grounding comment under **Grounding to-do** (the same always-on list as `/ai-slop:review`, restricted to changed citations). For newly cited keys, also run `python3 "<skill-dir>/../../scripts/verify_references.py" <bibfiles> [--mailto you@example.org]` and report flagged entries cited in newly added `\cite{}` calls under **Reference verification** (advisory and dependent on network access, exactly as in `/ai-slop:review` step 6).

11. **Write the report.** Save `ai-slop-report.md` in the working directory. As in `/ai-slop:review`, the report must never be committed. Resolve the repository root with `git rev-parse --show-toplevel` and, when the top-level `.gitignore` does not already list `ai-slop-report.md`, append that line (creating the file if absent).

    Then run `python3 "<skill-dir>/../../scripts/lint_markdown.py" --fix ai-slop-report.md`. If the linter exits non-zero, read its stdout findings (one per line, tab-separated `<file>:<line>\t<rule>\t<message>`), revise the report in place to address each, and re-run the linter. Repeat at most three iterations. After the third pass, proceed regardless of what the linter reports. The lint loop is internal quality control. Do not mention lint output, rule names, exit codes, or iteration counts in the user-facing summary.

    Then Read the file back and quote its contents verbatim in your reply. Do not regenerate the report text from memory for the inline echo, which has triggered repetition glitches (duplicate disclaimer blockquotes and `## Summary` headings). Echoing the Read result keeps the printed version identical to the file. Use the report template from `../review/SKILL.md` "Report template" with one extra header line:

    ```text
    **Diff scope:** base=<base ref>, files=<list of changed files in the diff pathspec>
    ```

    Place this line under `**Reviewed:**`. The Summary should explicitly note that the review only covered changed lines, so a reader of the report does not assume that the rest of the paper was checked.

12. **Stop after the report.** Do not modify the paper. If the user wants the findings applied, route them to `/ai-slop:revise`. The schema is identical, so revise mode works without changes.

## Report template

Identical to `/ai-slop:review` (same `Rule` / `Location` / `Quote` / `Suggested revision` schema so `/ai-slop:revise` can act on it), with the extra `**Diff scope:**` header line described in step 11. See `../review/SKILL.md` "Report template" for the full template.

## Bundled files

- `../../shared/rules-general.md`, `../../shared/rules-scientific.md`, and `../../shared/rules-latex.md` are the three rule layers, and `../../shared/rules-ste.md` is the optional STE layer. Load the subset that each changed file calls for (step 6).
- `../../scripts/find_latex_root.py`, `../../scripts/detect_scope.py`, `../../scripts/fetch_tropes.py`, `../../scripts/scan_glyphs.py`, `../../scripts/scan_reference.py`, `../../scripts/scan_repeats.py`, `../../scripts/scan_sentences.py`, `../../scripts/find_citation_issues.py`, `../../scripts/check_bib_fields.py`, `../../scripts/verify_references.py`, and `../../scripts/lint_markdown.py` implement the deterministic checks above (root and scope detection; the catalog download; the glyph, reference, repeat, and sentence scans; citation issues; BibTeX field and reference verification; and report linting). Their module docstrings document inputs, outputs, exit codes, and known limitations.

## Constraints

- **Diff scope is strict.** Only flag a finding when at least one line of its quote is in the changed-line set. Do not report pre-existing issues on untouched lines, even when they are inside a changed paragraph.
- **Same report schema.** The report must match the schema produced by `/ai-slop:review` so `/ai-slop:revise` works without changes. The only difference is the extra "Diff scope" header line and the scoping note in the Summary.
- **Do not modify the paper.** Diff mode writes only `ai-slop-report.md` in the working directory, plus the report name in the top-level `.gitignore` when that line is missing (step 11).
- **Do not stash, commit, or alter the working tree.** The skill reads the diff and the working-tree files. It never runs `git add`, `git stash`, `git commit`, or any other state-changing git command.