# Suggestion diff > The model rewrote a paragraph and the viewer has to see exactly what changed before agreeing to it. - Canonical: https://patterns.konigi.com/ai-assistants/suggestion-diff - Group: In-product assistance - Level: implementation - Status: published - Updated: September 12, 2026 - Also called: accept or reject, tracked change, proposed edit --- ## Problem A rewrite comes back and reads well. Whether it kept the one clause that mattered, changed a number, or dropped a qualifier is invisible, because a fluent replacement paragraph looks exactly like a fluent original paragraph. ## Solution Show the change rather than the result. Mark what was removed and what was added, keep both visible until a decision is made, and make accepting an explicit act. Version control has run on that contract for decades, and it earns its keep here for a sharper reason: a person reviewing their own prose can't reliably spot a single altered word by reading, and a model's rewrite changes many words at once. Granularity is the decision that separates a useful implementation from a frustrating one. A single accept-or-reject over a whole rewritten section forces an all-or-nothing judgement on a change that's usually eighty per cent good. Splitting the proposal into hunks, each independently acceptable, is what lets the viewer keep the tightened opening and reject the sentence that lost the caveat. Per-hunk controls cost more to build and are the difference between a feature people use and one they try twice. Presentation depends on the material. Inline marking, with deletions struck and insertions underlined, keeps the change in its surrounding context and reads well for small edits in prose. Side-by-side is better for a heavy rewrite, where inline marking produces an unreadable tangle of overlapping changes. Structural edits want a summary above the diff, because a reader can't reconstruct "these three paragraphs were reordered" from a set of insertions and deletions. The word-level detail matters for prose more than for code. A line-based diff on a reflowed paragraph reports that the whole paragraph changed, which is technically true and useless. Word-level or sentence-level granularity is what makes a prose diff readable at all. Reversal is the part that gets skipped. Accepting should be undoable as a single step, and a viewer who accepted six hunks and changed their mind shouldn't be reversing six operations. HAX guideline 9 asks for efficient correction, and in this pattern the correction is frequently of the acceptance rather than of the model. ## Use when The model proposes changes to material the viewer owns and will be held responsible for. ## Don't use when The output is new content with no prior version. There's nothing to diff against a blank space, and framing a first draft as a proposed change adds ceremony to an operation that's just insertion. ## Trade-offs Diffs are the honest presentation and they're harder to read than clean text, so viewers under time pressure accept without reading and get the worst of both. Per-hunk controls give real granularity and clutter the document with decision points. Side-by-side preserves clarity at the cost of half the width, which hurts most at the widths where prose is already tight. A diff also makes the model's changes look larger than they are. An edit touching many small things reads as extensive even when it's trivial. ## Checklist - Is the change shown at word level, or only line level? - Can individual hunks be accepted separately? - Is one undo enough to reverse an acceptance? - Does a structural change get a summary as well as a diff? - What does the diff look like on a fully rewritten paragraph? - Is the original recoverable after accepting? - Are additions and deletions distinguished by something other than colour? - Does it work at a narrow width without forcing a horizontal scroll? - Can the viewer edit the proposal before accepting it? - Is there a clear state for a proposal nobody has decided on yet? ## Compare **GitHub Copilot** delivers its review as pull request comments with suggested changes, so the proposal enters an existing review workflow and inherits its per-hunk accept controls rather than inventing new ones. **Notion** presents its rewrite as a proposal with accept, discard and retry, keeping the original in place until the viewer decides. **Google Docs** routes the equivalent through suggestion mode, where a model's edit becomes the same object as a colleague's and carries the same accept and reject affordances. **Cursor** shows code edits as an inline diff in the editor with per-hunk keys. It's the finest-grained version of the pattern, and the one assuming the most expert reader. ## Related Inline assist is what usually produces the proposal. Ghost text is the lighter form for changes small enough not to need a diff. Artifact panel is where a large proposed document goes. Code block actions covers applying a snippet rather than reviewing a change. Response actions is the equivalent control row in a conversation. ## Related patterns - [Inline assist](https://patterns.konigi.com/ai-assistants/inline-assist) — The viewer wants one paragraph changed and does not want to leave the document to ask for it. - [Ghost text](https://patterns.konigi.com/ai-assistants/ghost-text) — A suggestion has to be readable in place and obviously not yet real. - [Artifact panel](https://patterns.konigi.com/ai-assistants/artifact-panel) — The answer is a document or a program, and a chat transcript is the wrong container for either. - [Code block actions](https://patterns.konigi.com/ai-assistants/code-block-actions) — Generated code gets read in one place and used in another. - [Response actions](https://patterns.konigi.com/ai-assistants/response-actions) — Copying, rating, sharing and rerunning all attach to one message, and none of them can dominate it. ## Sources - [GitHub, Request a code review from Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review) - [Microsoft HAX Toolkit, Guideline 9, Support efficient correction](https://www.microsoft.com/en-us/haxtoolkit/guideline/support-efficient-correction/) - [Notion, Everything you can do with Notion AI](https://www.notion.com/help/guides/everything-you-can-do-with-notion-ai) --- Screenshots on patterns.konigi.com are reproduced for commentary and criticism. Product names and marks belong to their owners.