The diff preview
Before-and-after for anything the agent is about to change.
Before an agent edits a file, a PR, a doc, an email, the user needs to see what's about to change. Most products ship one diff view and call it done. The good ones ship three: side-by-side for structure, inline for scanning, prose for skimming. Different moments call for different views.
"A diff is not a format. It's three formats: the reviewer picks which one fits the moment."
Three views, one decision.
A toggle at the top of the diff lets the reviewer switch between views without re-running the agent. Side-by-side shows structural shape. Inline highlights line-level change. Prose summary describes the intent in one-sentence bullets. Approve/tweak/discard sits at the bottom, always in the same place.
function getUser(id) {
const u = db.get(id);
return u;
}async function getUser(id) {
const u = await db.get(id);
if (!u) throw new NotFoundError(id);
return u;
}Three views of the same change. Reviewers need all three for different moments.
Reviewers read code and prose differently.
A structural change ("made this function async") is easier to grasp as a prose summary than as red-and-green lines. A rename across thirty files is easier as an inline list. A first-pass review of a new feature wants the side-by-side, where you can hold the whole before-state in one half of the screen.
Diff hygiene that matters.
- Line counts up top. +3 / −2. Before the user reads anything, they know the shape of the change.
- Decision bar pinned. Approve, tweak-prompt, discard. Same three buttons, same place, every time.
- Prose summary reasons. Not a list of changed lines — a list of intents. "Made it async." "Added not-found guard." The summary is the reviewer's first pass.
Diffs that hide the irreversible part.
Some diffs render cleanly but the act of applying them triggers side effects the diff didn't show — emails sent, hooks fired, notifications cascading. The reviewer approves the file change, not the knock-on. That's a trust leak that gets discovered the hard way.
What this pattern gets wrong when it gets wrong.
- Runaway agent
- An agent that loops, spends, or edits past the user's intent with no visible cap.
- Silent truncate
- The response ran out of room or tokens and the product didn't tell the user where it stopped.
- Phantom tool
- A visible tool call that didn't happen, or happened but with different arguments than shown.
Three shipping variants worth copying.
- Side-by-side diff for files, inline diff for prose
- A 'select all adds, reject all removes' shortcut
- A preview of the post-merge result above the diff