I Stopped Eyeballing Agent Diffs, and the 2.8.0 View Limits Are Why

Split the Diff Into a Digest and an Artifact

The new rule is simple. Stop handing a raw diff to a human. Produce two things instead:

1. A digest with a fixed length. It carries what a machine already decided, plus pointers to where a human should start.
2. The full patch, written to a file. Never discarded, but never opened by default.

The fixed length is what matters. Whether the change is 400 lines or 4,000, the first thing you read is the same size. Review time stops tracking diff size.

Here is the current version (v2), after the November re-check. It differs from the August script in the three places marked 1) to 3) in the comments.

#!/usr/bin/env bash
# review-digest.sh v2 — split a diff into a one-screen digest and a full artifact
# usage: ./review-digest.sh              uncommitted work (new files included)
#        ./review-digest.sh origin/main  against a revision (new files included)
# written for macOS's stock bash 3.2: no arrays, no mapfile
set -uo pipefail
 
BASE="${1:-HEAD}"
OUT_DIR="${REVIEW_OUT_DIR:-.review}"
mkdir -p "$OUT_DIR"
FULL="$OUT_DIR/diff-full.patch"
NEW_LIST="$OUT_DIR/untracked.lst"
 
# 1) temporarily mark untracked files intent-to-add so they appear in the diff
git ls-files --others --exclude-standard -z -- . ":(exclude)$OUT_DIR" > "$NEW_LIST"
if [ -s "$NEW_LIST" ]; then
  xargs -0 git add -N -- < "$NEW_LIST"
  # 2) always undo it on exit, so stash and commit -a are not affected
  trap 'xargs -0 git reset -q -- < "$NEW_LIST"' EXIT
fi
 
git diff "$BASE" > "$FULL"; STATUS=$?
if [ "$STATUS" -ne 0 ]; then
  echo "git diff failed (exit=$STATUS)" >&2
  exit "$STATUS"
fi
STAT=$(git diff --stat "$BASE" | tail -1)
NUMSTAT=$(git diff --numstat "$BASE")
 
# 3) keep added lines only, and strip the leading + before checking
ADDED=$(grep -E '^\+' "$FULL" | grep -vE '^\+\+\+ (b/|/dev/null)' | sed 's/^+//' || true)
 
E_BANG=$(printf '%s\n' "$ADDED" | grep -c '\\!' || true)
BARE=$(printf '%s\n' "$ADDED" | grep -E '(^|[[:space:]])https?://' \
        | grep -vE '\]\(|<https?://|"https?://' | grep -c . || true)
MDTBL=$(printf '%s\n' "$ADDED" | grep -cE '^[[:space:]]*\|[-: |]+\|[[:space:]]*$' || true)
NEWCOUNT=$(tr -cd '\0' < "$NEW_LIST" | wc -c | tr -d ' ')
 
echo "== change size =="
echo "  ${STAT:-  (no changes)} (new files: ${NEWCOUNT})"
echo
echo "== machine findings (fix these before opening the full patch) =="
echo "  stray \\! escapes     : ${E_BANG} lines"
echo "  bare URLs             : ${BARE} lines"
echo "  markdown table rules  : ${MDTBL} lines"
echo
echo "== needs human eyes (largest changes first) =="
printf '%s\n' "$NUMSTAT" | sort -rn | head -5 | while read -r add del path; do
  [ -z "${path:-}" ] && continue
  printf '  %5s+ %5s- %s\n' "$add" "$del" "$path"
done
echo
echo "full patch: $FULL ($(wc -l < "$FULL" | tr -d ' ') lines)"
 
# exit non-zero when anything was found
[ "${E_BANG:-0}" -eq 0 ] && [ "${BARE:-0}" -eq 0 ] && [ "${MDTBL:-0}" -eq 0 ]

Dropping in a new file with one line of each defect produces this (November 2026, Ubuntu 22.04, git 2.34.1, bash 5.1):

== change size ==
   1 file changed, 3 insertions(+) (new files: 1)
 
== machine findings (fix these before opening the full patch) ==
  stray \! escapes     : 1 lines
  bare URLs             : 1 lines
  markdown table rules  : 1 lines
 
== needs human eyes (largest changes first) ==
      3+     0- _probe.md
 
full patch: .review/diff-full.patch (9 lines)

Exit code 1, and afterwards git status --short still showed ?? _probe.md — the repository was back exactly where it started. Twelve lines to understand the situation and know what to fix.

The First Version Found Nothing at All

When I first ran the August prototype, all three counters read zero. This was immediately after I had planted a file containing all three defects.

The cause is git diff HEAD: untracked files do not appear in a diff. When an agent creates a new file, its entire contents fall outside the check. Newly created files are the ones you most want inspected, and by default they pass through untouched.

The fix is intent-to-add (git add -N). Registering only the file's existence in the index makes its body show up as added lines.

I did not know about the last two rows in August. More on them in the next section.

A gate you believe is running while it inspects nothing is a real failure mode. Whenever you add one, feed it an input that must fail and confirm that it does. The same canary idea — proving a mechanism actually fires rather than merely loads — is how I approached hooks that load but never run.

Three More Holes I Found in November

I re-ran the August script against the same defect-laden file in November. It did not go well, and every cause was in how I had written it.

Hole 1: bare URLs at the start of a line counted as zero

The August version checked added lines with their leading + still attached. The bare-URL rule matches https:// at the start of a line or after whitespace, so a line like +https://example.com starts with + and never matches.

URLs pasted mid-paragraph were caught; a URL alone on its own line — the most common way people paste one — was not. The sample output I published in August showed one bare URL. Re-running the same input in November showed zero. I believe I skipped the re-check when copying the output into the article.

v2 strips the leading + with sed 's/^+//' before any check, and the table-rule regex no longer assumes the + is there.

Hole 2: passing a revision made new files vanish

The August version only ran git add -N in the no-argument branch. Call it as ./review-digest.sh origin/main and untracked files never reached the diff; the script reported nothing and exited 0.

Having an agent work on a branch and comparing against origin/main is the use I actually cared about most. That was exactly the call that slipped through.

Hole 3: intent-to-add was never undone

In August I wrote that intent-to-add "does not stage anything, so it leaves your later git add behavior alone." That was only half true.

First, git commit -a. An intent-to-add file counts as tracked, so commit -a picks it up. The official git add documentation for -N even lists committing such files with git commit -a as one of its uses. A throwaway probe file can end up in history without you noticing.

Second, git stash. On my git 2.34.1, a leftover intent-to-add entry made it fail like this:

error: Entry 'new2.md' not uptodate. Cannot merge.
Cannot save the current worktree state

This combination has been reported repeatedly on the git mailing list, and behavior may differ by version, so it is worth checking once on whatever git you have.

v2 writes the untracked list to untracked.lst before starting and uses trap ... EXIT to git reset -q -- those paths on the way out. Whether the script crashes midway or exits non-zero because it found something, the index ends up where it was.

Piping the Digest to head Throws the Verdict Away

One more thing surfaced after a few days of use. The digest grew a little, so I trimmed it at the call site:

./review-digest.sh | head -20   # the verdict is now gone

By default a pipeline exits with the status of its last command. head succeeds, so even when the script returns 1 the caller receives 0. Findings are detected and nothing stops.

The tempting fix is set -o pipefail at the call site. When I tried it, a different problem appeared: with something like | head -1 that stops reading early, the script dies of SIGPIPE and you get 141 even when there are zero findings. Now it stops when it should not. I measured when that false red shows up in the pipefail check that turned red once output grew.

Keeping the digest short is the script's job, so the call site should just run it. When trimming is unavoidable, resolve the verdict first:

if ./review-digest.sh > .review/digest.txt; then
  echo "no machine findings"
else
  head -20 .review/digest.txt   # trim only after the verdict is captured
  exit 1
fi

Truncation drops more than it appears to.

Troubleshooting by Symptom

These are the symptoms I actually ran into after adopting the routine, with how to confirm each and how to fix it. Working down the list from the top tends to find the cause quickly.

Where to Put the Check, and How I Choose

The idea — let a machine clear the mechanical defects first — stays the same, but there are several places to run it. Here are the ones I tried or considered.

In my situation I run the digest by hand at each checkpoint and also put the same script in the first CI job — locally to notice early, in CI as a gate nobody can skip. Whenever I relied on only one of them, there was always a day I forgot the local run.

Three Common Misreadings

"The view cap means part of the diff is lost"

The cap applies to what the viewer displays, not to the diff data. Write git diff to a file and the whole thing is still there. What 2.8.0 changed is the default for how much is shown.

"git diff HEAD includes new files"

It does not. With or without HEAD, and with origin/main as the revision too, untracked files never appear. If you want an agent's new files inspected, you have to tell the index they exist, for example with intent-to-add.

"Every \! is a bug"

In a shell, find . \! -name "*.bak" is perfectly valid, and v2 counted that line as a finding when I tried it. The digest's number is a list of things to look at, not a list of things to fix. When it is non-zero, pull the lines with grep and judge them per language. In my article repository, I treat \! inside JavaScript and TypeScript code blocks as a defect.

Deliberately Narrow What a Human Looks At

Once the digest passes, I open only the top two or three files by change size, and I look strictly for things a machine cannot judge:

• Does the prose say the same thing as the code beneath it?
• Is the reason for the chosen approach written down anywhere?
• Was the described behavior actually verified?

The dangerous code an agent writes is rarely the code that fails to parse. It is the code that parses cleanly while drifting slightly from its own description. Machines catch the first category reliably; only people catch the second. Since splitting the roles, I notice the second kind more often. Reading everything meant spending my attention before I ever got there.

Whether to let a machine pick those top files at all is a separate decision. I measured whether ordering by change size actually pays off in sorting diff review order by machine, tested on 106 commits.

Living With the Caps

The 2.8.0 caps apply to the viewer and to large history diffs. They do not remove the times you genuinely need the whole thing. My split looks like this:

The full patch is on disk, so it is there when I want it. The cap is on the viewer, not on the data. Once that distinction was clear, the change stopped feeling like a restriction and started feeling like a different default.

Three Steps to Put This in Place

Setup takes about fifteen minutes. This is the order I used.

1. Drop the script in and ignore its output directory

Put review-digest.sh at the repository root or under scripts/, and make it executable. Add .review/ to .gitignore. v2 already excludes .review/ from the untracked list, but without the ignore rule git status gets noisy on every run.

chmod +x review-digest.sh
echo ".review/" >> .gitignore

2. Feed it something that must fail, and confirm it cleans up after itself

Skipping this is how you end up with the detector that detects nothing. Write a throwaway file holding one line of each defect and run the script both with no argument and with a revision. Both should exit 1, and git status should not show an A afterwards.

printf 'if (\\!ok) {}\nhttps://example.com\n| --- | --- |\n' > _probe.md
./review-digest.sh > /dev/null; echo "no-arg exit=$?"      # 1 means it is working
./review-digest.sh HEAD > /dev/null; echo "HEAD exit=$?"   # 1 means it is working
git status --short _probe.md                               # still ?? means clean-up worked
rm _probe.md

3. Put it ahead of your existing checks

In a production pipeline, place it before the expensive steps — tests, builds, linters. There is no reason to spend a full build on a two-character anomaly.

./review-digest.sh > .review/digest.txt || { cat .review/digest.txt; echo "machine findings; fixing first"; exit 1; }
npm run lint && npm test

Nothing existing has to be replaced; the digest only goes in front. Runtime stays essentially flat regardless of diff size: with a 3,000-line new file in the diff, it finished in under 0.1 seconds on my machine.

What to Do Next

If you use a similar digest script, check once — using the call that passes a revision — whether a new file full of defects really makes it fail. Mine let that call through for three months.

I still have only three checks in the digest and I am adding them one at a time. If you have found a check worth including, I would like to hear about it.