Change review

Problem Context

• Proposed changes may come from collaborators, reviewers, editors, code suggestions, AI edits, merge requests, tracked changes, document suggestions, conflict recovery, dependency updates, or automated refactors.
• Reviewers need enough context to understand why the change exists, what it touches, what remains unresolved, and whether accepting it will commit content, create a patch, resolve a thread, or only submit feedback.
• A change can become outdated when the underlying file, branch, paragraph, version, or suggestion thread changes after the reviewer loaded it.
• Review decisions may be individual, batched, file-scoped, visible-only, all-suggestions, pending-review, required-review, permission-limited, or informational depending on product rules.

Selection Rules

• Choose change review when users are inspecting proposed edits, diffs, suggestions, tracked changes, or review comments before accepting, rejecting, applying, or requesting changes.
• Use review before submit when the user checks their own captured answers before a transaction, not when they judge proposed edits.
• Use approval workflow when the primary job is routed authorization with required approvers and downstream blocking.
• Use review queue when the primary job is processing many queued items and choosing what to handle next.
• Use comments when the surface only supports discussion and does not decide whether a change is accepted or rejected.
• Use compare view when there is no proposed-change lifecycle or decision state.
• Use version history when users browse previous accepted states rather than pending or proposed changes.
• Use activity log when users need historical records after change review decisions happen.
• Show original content, proposed content, changed scope, author, status, stale state, and decision consequence before action.
• Make single-change, visible-only, batch, file-level, and all-change actions visually and textually distinct.
• Keep pending review comments, submitted comments, resolved threads, outdated threads, and requested changes distinct.
• Disable or explain accept, reject, apply, approve, and request-change controls when permissions or freshness checks fail.

Required States

• Default change review state with original and proposed content visible.
• Single suggested edit or tracked change state.
• Diff hunk with line comment state.
• Pending review comment state before submission.
• Submitted review state with comment, approve, or request changes outcome.
• Accepted, rejected, applied, or dismissed change state.
• Batch suggestions or accept-all scope preview state.
• Stale, outdated, or changed-since-review state.
• Marked viewed and unviewed file state.
• Unresolved and resolved conversation state.
• Permission-limited or read-only reviewer state.
• Mobile condensed change navigation state.

Interaction Contract

• Selecting a change reveals the base content, proposed content, author, context, and exact scope affected by a decision.
• Accept, reject, apply, dismiss, approve, comment, request changes, and mark viewed actions update the same change or review record and expose the resulting status.
• Batch actions preview included changes, excluded hidden changes, conflicts, stale suggestions, and permission exceptions before commit.
• Pending review comments remain private to the reviewer until the review is submitted, and the UI labels that privacy clearly.
• A stale or outdated change cannot be applied silently; the user must refresh, re-review, or resolve conflict.
• A rejected or dismissed change preserves enough rationale, thread status, or activity record for collaborators to understand the decision.
• Keyboard and screen-reader users can move to next and previous changes, understand insertion and deletion text, and submit or abandon a review without losing comments.
• After each decision, focus moves to the next unresolved change, changed status, or review summary rather than resetting the page.

Implementation Checklist

• Define change record fields: base content, proposed content, location, author, timestamp, source, status, reviewer, pending comments, thread state, freshness token, permission scope, and batch eligibility.
• Separate proposed-change records from comments, activity-log events, version snapshots, approval routes, review queues, and final-submit summaries.
• Build diff or redline rendering that labels insertions, deletions, replacements, file names, line ranges, document sections, and hidden unchanged context.
• Implement next and previous navigation, mark viewed, pending comment drafts, submit review, abandon review, accept, reject, apply, batch, and request-change flows.
• Check freshness and permissions before applying or accepting a change, especially after new commits, document edits, branch updates, or conflict resolution.
• Preview batch scope and exceptions for hidden changes, filtered files, stale suggestions, mixed permissions, unresolved conversations, and broad accept-all decisions.
• Preserve decision rationale, thread resolution, audit event, and focus position after individual and batch decisions.
• Test long diffs, whitespace-only changes, image or binary files, mobile line wrapping, high zoom, keyboard diff navigation, screen reader text alternatives, stale suggestions, and permission-limited reviewers.

Common Generated-UI Mistakes

• Showing accept and reject controls without original and proposed content.
• Using approval workflow for every change review even when no routed approver policy exists.
• Calling a review queue change review when reviewers are only choosing which item to open next.
• Making pending comments look submitted.
• Letting broad accept-all controls appear beside a single visible suggestion without scope copy.
• Applying stale suggestions after the underlying content changed.
• Resolving or deleting discussion threads without preserving decision rationale.
• Treating visual compare as enough when users need decision state, comments, and submission.

Critique Questions

• What exact original content and proposed content is the user deciding on?
• Does each control say whether it affects one change, visible changes, a batch, a file, or all changes?
• Can reviewers distinguish pending comments from submitted feedback?
• How does the UI prevent stale, outdated, or permission-limited changes from being applied?
• What happens to comments, threads, viewed state, approvals, and activity records after accept or reject?
• Would review before submit, approval workflow, review queue, comments, compare view, version history, or activity log better fit this surface?