devex
Inline diff UX that reduces review fatigue
Inline diff UX displays code changes within the final file structure instead of side-by-side comparisons, reducing cognitive load during code review.
Code review fatigue starts when a reviewer opens a diff and can't immediately tell what changed or why. Classic unified diffs force you to reconstruct the before-and-after state in your head while scrolling vertically through hundreds of lines. Side-by-side views dedicate half your screen to the "before" state, making you toggle mentally between old and new while your spatial memory of the file degrades. When an AI agent generates changes across twenty files—or when you're reviewing a sprawling refactor—the red-green line soup becomes unreadable. You lose the forest for the trees.
Inline diff UX solves this by collapsing unchanged context and rendering additions and deletions directly within the final file structure. Reviewers evaluate the actual code that will land, not a fractured before-and-after comparison. Done right, this cuts review time and catches more logic errors because you're reading coherent source code with change annotations, not parsing abstract deltas.
We've built inline diff tooling at Goatfied because our agent loop produces dozens of small, reversible edits per coding session. Each iteration goes through plan → constrain → edit → validate → retry, generating focused mutations: add a null check here, extract this method, update three call sites. Reviewers need to verify each change matches the agent's stated plan without re-reading entire files. This post walks through the concrete design decisions that made our inline diff view useful, from character-level highlights and collapsible regions to validation badges and multi-file coherence.
Surface character-level changes, not just line replacements
Most diff engines highlight full lines as removed or added. When an agent renames a variable or tweaks a string literal, a line-level diff paints the entire line red and green even though only three characters changed. Your eyes scan the whole line hunting for the delta.
Character-level diffing solves this by marking only the substring that differs:
- const maxRetries = 3;
+ const maxAttempts = 3;
In an inline view, Retries appears struck through or faded in red and Attempts in green within the same visual line. The rest of the identifier and = 3; remain neutral. Your brain processes "renamed one word" instead of "deleted a line and added a nearly identical one."
Implementation-wise, libraries like diff-match-patch or Myers diff with word-level tokenization can generate these sub-line hunks. The trick is balancing granularity: diff every Unicode scalar, and you get noisy highlights around punctuation; diff only whole words, and you miss small typos. We settle on word boundaries plus special handling for camelCase and snake_case splits, so maxRetries → maxAttempts shows a single swap rather than treating the entire token as changed.
This matters especially for AI-generated diffs. When an agent adjusts error messages across ten files, character-level granularity shows that it changed "Invalid request" to "Invalid API request" in each location—reviewers verify consistency without mentally diffing full strings.
Collapse unchanged context aggressively
Inline diffs shine when they hide the 90% of code that didn't move. Traditional side-by-side views often pad both columns with unchanged lines "for alignment," forcing you to scroll past boilerplate to reach the next edit. Unified diffs interleave unchanged context with hunks, but without visual hierarchy you're still scanning linearly through noise.
We render unchanged regions as collapsible blocks with a single-line summary: … 47 unchanged lines …. Clicking expands them if you need surrounding context, but the default is compressed. This mirrors how you'd skim a PR description that says "renamed three methods in api.ts"—you trust the summary until something smells off.
The core trade-off: how many unchanged lines do you show between edits before collapsing? Too aggressive and you lose the surrounding function or class definition that explains why the edit makes sense. Too conservative and you're back to scrolling through boilerplate. A practical starting point: show three lines of context above and below each hunk. If two hunks are separated by fewer than six unchanged lines, don't collapse—just show the connecting lines. This keeps small functions entirely visible while still folding large blocks of imports or test fixtures.
For AI-generated diffs, add a heuristic: if the unchanged gap contains a function or class boundary (detected by parsing the AST or counting indent changes), always show at least the signature line. Reviewers need to know "this edit lives inside processPayment()" without clicking to expand. In practice this might mean showing five to eight lines of context around structural boundaries, even if your base threshold is three.
Make folds interactive. Click to expand inline, with the expanded region staying open until you collapse it again. Avoid auto-collapsing on scroll—nothing frustrates a reviewer faster than losing their place because the UI decided they were "done" looking at that section.
Anchor diffs to validation outcomes
Goatfied's agent loop runs a compile/lint/test gate after every edit. If the gate fails, the agent retries with a corrected diff. This means each proposed change has an associated validation result: pass, fail, or skipped (for drafts).
We embed that result directly in the inline diff UI. A green checkmark badge next to a hunk tells you "this compiles and passes tests." A red X indicates "this broke the build; see stderr below." The reviewer can immediately prioritize: green hunks might be auto-approved or skimmed lightly, red hunks demand scrutiny to understand whether the breakage is expected (work-in-progress) or a real bug.
This design decision—tying diff visibility to validation—reduces review fatigue by offloading the "does this even work?" question to tooling. In a purely manual review, you'd mentally execute the code or spin up a local build. Here, the system already ran cargo check, eslint, and unit tests, and the diff UI surfaces that data inline.
From a UX perspective, the diff component subscribes to a validation event stream. When the agent completes an edit and the validation pipeline finishes, we update the hunk's badge asynchronously. Reviewers see diffs accumulate in real time, each one stamped with pass/fail metadata as results arrive.
For self-hosted setups, wire your CI output directly into the diff view. Parse test failures, extract line numbers from stack traces, and pin them to the corresponding added or changed lines. The goal: make the diff the single pane of glass for both "what changed" and "does it work."
Use progressive disclosure to surface risk
Not all changes carry the same weight. A diff that adds a new external API call, changes a database query, or modifies error-handling logic deserves immediate attention. A diff that updates a test fixture or adds a log line can wait.
Implement a simple risk scoring heuristic:
- High risk: Type signature changes, new external I/O (network, filesystem, database), authentication/authorization logic, destructive operations (delete, drop, truncate), concurrency primitives (locks, channels, promises).
- Medium risk: New function definitions, control flow changes (adding branches, loops), dependency upgrades.
- Low risk: Test-only changes, comments, logging, variable renames within a single function.
Render high-risk diffs at the top, expanded by default. Collapse medium and low into labeled sections ("3 test updates," "2 comment changes") that reviewers can skip or expand as needed:
🔴 High-risk changes (2)
auth.ts: function signature change
db.ts: new DELETE query
🟡 Medium-risk changes (4)
api.ts: new function `handleRefund`
...
⚪ Low-risk changes (12) [collapsed by default]
✓ 8 test fixture updates
✓ 4 comment clarifications
This doesn't eliminate review—it just front-loads the cognitive load on what matters. A reviewer can scan the high-risk section in 90 seconds, verify the tests cover it, and defer the boilerplate until they have time later.
For languages with robust parsers (TypeScript, Go, Rust, Python), you can go further: detect when a function body was extracted but the original call site now just invokes that new function. Show this as a single "refactor: extracted handleAuth()" block instead of 40 deleted lines + 40 added lines elsewhere. The UX communicates intent, not raw line edits.
Provide a unified timeline, not just spatial diffs
A single pull request in an agent-assisted workflow might contain twenty micro-edits: rename a variable, add a null check, update a dependency version, refactor a helper. Showing all twenty as a flat list of file diffs loses the narrative—which edit addressed which part of the plan?
We render diffs in a timeline view: each edit is a card with a timestamp, the agent's commit message (e.g., "Implement retry logic with exponential backoff"), the inline diff, and the validation badge. Reviewers scroll chronologically, seeing how the agent iterated from draft to working code. This structure mirrors the agent loop's plan → edit → validate → retry cycle and makes it obvious when the agent had to backtrack.
The timeline also supports collapsing entire edits. If you trust that "Update ESLint config" is low-risk, fold that card and focus on the business logic changes. Conversely, if an edit failed validation twice before passing, you can expand all three attempts in the timeline to understand what went wrong.
Technically, this requires storing each diff as a discrete artifact keyed by edit ID and timestamp, not just the final file state. We persist these as lightweight JSON blobs indexed by session and plan step, so the UI can reconstruct the sequence on demand.
Handle merge conflicts and concurrent edits gracefully
When an agent operates on a branch that diverges from main, or when a human makes a manual edit mid-session, traditional diff views break down. You get cryptic three-way merge markers or silent overwrites.
Our inline diff detects conflicts by running a three-way merge (base, ours, theirs) and highlights conflicting hunks in amber. The reviewer sees both the agent's proposed change and the conflicting manual edit, with a prompt to resolve: keep agent's version, keep manual, or merge manually. This prevents the silent data loss that kills trust in automated tools.
For true merge conflicts, render conflict markers inline with syntax-aware formatting. Instead of raw <<<<<<< HEAD strings, use collapsible sections labeled "Your version" and "Incoming version," each syntax-highlighted. Let the reviewer pick one, edit both, or write a third option, all without leaving the inline view.
When an AI agent makes multiple passes—plan, edit, validate, retry—you sometimes see overlapping changes in the same region. One transparent approach: annotate the diff with iteration markers. Show the original line, then a faded "Agent attempt 1" layer with the first edit, then "Agent attempt 2" with the refinement. This adds visual complexity but builds trust—reviewers can see the agent self-correcting, which matters when they're deciding whether to accept a generated change in a critical code path.
Support per-hunk controls for granular approval
Monolithic approve/reject flows force all-or-nothing decisions. Inline diff UX should let reviewers act on individual hunks:
- Accept hunk: merge this specific change into the working branch immediately (or stage it for batch commit).
- Reject hunk: discard without affecting other edits in the same file.
- Edit in place: modify the proposed lines directly in the inline view, triggering a new agent retry or validation pass.
This granularity cuts iteration cycles. Instead of commenting "looks good except line 47," then waiting for the author to fix and re-request review, a reviewer edits line 47 inline, runs tests, and approves the rest in one session.
Practically, this requires Git-level integration that can create partial commits from accepted hunks, plus validation hooks that re-run linters or type checkers after inline edits. Each hunk should show "pending," "accepted," or "rejected" without requiring mental bookkeeping.
The Goatfied agent loop handles this by re-validating after every hunk acceptance, so reviewers know immediately if their inline edit breaks a test or type constraint.
Preserve spatial layout and context
Indentation, line numbers, and block structure must match the final file exactly. If the diff renderer reflows code or collapses whitespace, reviewers lose spatial anchors. You want to skim a diff the same way you skim source code—top to bottom, with consistent rhythm.
This matters for catching logic errors. If an async/await change is buried in a reformatted block, the reflow obscures the actual risk. A reviewer needs to see whether new code runs inside a try/catch, or whether it's guarded by a null check three lines up.
Minimal visual noise helps. Deleted lines appear as faded strikethrough text, not bright red blocks. Additions are underlined or lightly highlighted, not neon green. The goal is to let your eyes track the final code normally, with changes visible but not distracting.
Show enough unchanged code that reviewers can verify new logic respects existing guard clauses, doesn't shadow variables, or correctly handles edge cases already present. For example, an AI agent proposes adding a null check:
function processOrder(order: Order) {
const discount = calculateDiscount(order.items);
if (!order.user) throw new Error('Missing user');
const tax = calculateTax(order.user.region, discount);
return applyPayment(order, tax);
}
Without seeing calculateTax requires order.user.region, a reviewer might approve the null check as defensive programming. With context, they see it's mandatory and should happen earlier—before calculateDiscount if that also touches order.user.
Make multi-file changes coherent
A rename or interface change touches 10+ files. Inline diff UX fails if reviewers must jump between files manually. Two practical solutions:
1. Linked hunk navigation: clicking on a function call in file A that was affected by a signature change in file B jumps to B's corresponding hunk, with both diffs visible in split subpanes.
2. Automatic grouping by semantic intent: the diff tool clusters related hunks (e.g., all hunks that rename processPayment to processTransaction) and presents them as a single reviewable unit, collapsible to a one-line summary.
Goatfied generates atomic, single-purpose diffs by default—each agent loop iteration targets one failing test or constraint—so multi-file changes naturally organize around a single problem. Reviewers see "Fixed TypeError in payment flow" with four files expanded, rather than four unrelated edits interleaved.
If you're batching changes, isolate risky ones. If an AI agent updates error messages in ten files, group those into one PR. If it also adds a new database migration, put that in a separate PR. Inline diffs work best when changes share a theme. Mixing cosmetic and structural edits in one view is cognitively expensive.
Add keyboard navigation and persistent review state
Reviewers working through a large diff need muscle memory: j to jump to the next hunk, k for previous, e to expand the current fold, c to collapse. Arrow keys scroll the viewport; single-letter commands navigate semantically. This isn't nice-to-have—it's the difference between reviewing fifty files in an hour versus a day.
Track review state per hunk. Mark each section as "approved," "needs discussion," or "pending." Persist this state in browser localStorage or push it to the server if you're building team workflows. When a reviewer returns after a meeting, they resume at the first un-reviewed hunk instead of re-scanning from the top.
Add a progress indicator: "12 of 34 hunks reviewed." This gives both psychological momentum and a concrete stopping point. If the diff is too large to finish in one session, the reviewer can confidently pause at hunk 20 and pick up tomorrow.
When inline diffs are the wrong tool
Inline rendering breaks down for:
- Large-scale refactors: Moving code between files, renaming modules, restructuring imports. You need a file tree view to understand the reorganization.
- Whitespace-heavy changes: Reformatting a 500-line JSON config with different indentation. The diff is technically small (just spacing), but inline rendering makes it look like everything changed.
- Schema migrations: Adding columns, changing foreign keys, renaming tables. You want a schema diff tool that shows logical changes, not raw SQL line edits.
In these cases, fall back to traditional side-by-side views or specialized diff tools. The goal is to match the UI to the change type, not force every diff into one paradigm.
Start by identifying what you can safely elide or collapse in typical PRs. An AST-aware diff can detect when only formatting changed versus when the function signature and query logic both shifted. Show the semantic change prominently; collapse the formatting noise to a single "formatting adjusted" line with an expand toggle.
Measure whether inline diff UX actually reduces fatigue
Teams adopting inline diff workflows should track:
- Time to first review action (accept/reject/comment): if this drops, reviewers are spending less time reconstructing context.
- Approval-without-comment rate on broken changes: run a canary where some PRs deliberately include subtle bugs. If approvals decrease, inline context is catching issues.
- Re-review cycles per PR: if reviewers can edit inline and re-validate immediately, you should see fewer round-trips.
Avoid vanity metrics like "total review time," which conflates review fatigue with PR complexity. The goal is higher-quality approvals in comparable time, not raw speed. What we see in our own workflows: PRs with inline diffs get first comments faster because reviewers don't wait to check out the branch. Comments focus on logic, not "I can't tell what this does" clarifications. Fewer "looks good" rubber-stamp approvals on risky changes, because the code is readable enough to actually evaluate.