**Status:** Draft for review **Author:** Aidan Foster **Date:** 2026-07-20 --- ## 1. Purpose Once a review run {#3585828} has produced findings and they are anchored on the rendered page (sibling: Render annotations markers over content + Link to suggestions cards), the editor needs to turn raw AI feedback into a deliberate plan. The agreed model is a two-step process: **step 1, build your task list** by reviewing each suggestion and deciding accept / ignore / report; **step 2, apply the changes** yourself on the edit form. This document specifies step 1 — the review tray where suggestions are triaged into an improvement plan. Keeping triage and apply separate was a deliberate decision (May 15/22 working sessions): there is no automated interaction with field widgets in v1, and the explicit extra step helps first-time users understand the flow. ## 2. Scope ### In scope * The review tray: intro state, findings list, filter chips, progress footer, completion CTA. * One suggestion card per finding, with the before/after suggested-change diff. * Decision actions per card: Accept, Ignore, Report — plus Undo. * Inline editing of the suggested replacement text. * Persistence of decisions (including edited text) with the review run. * The card side of the bidirectional card ↔ marker interaction (the marker side is owned by the sibling annotation document). ### Out of scope * Generating findings and the scoring thermometer — #3585828. * Parsing/anchoring markers onto the page — sibling annotation document. * Applying changes on the edit form (step 2) — sibling document. * Bulk "accept all" — deliberately excluded from v1 (see §10). * What Report triggers downstream (rule-owner notification, counters) — needs its own definition (§12). ### Assumptions * Findings arrive with criterion, title, rationale, suggested change, and an anchored marker (or an unanchored flag) per the sibling documents. * Criterion labels, letter codes, and colors are configured by the review creator (criterion-configuration ticket); the ones in the comps are examples. * The tray opens from the scoring thermometer specified in #3585828. ## 3. Entry workflows ### Workflow A — First open after a run The editor clicks the scoring thermometer; the tray opens showing the **intro state**: eyebrow "AI Content Review", review timestamp and suggestion count, and an explanation of the two-step process (1: build your task list — accept the suggestions you want to apply, ignore the rest; 2: apply the changes on the edit form). A "Start improvement plan" CTA drops the editor into the findings list. ### Workflow B — Returning mid-triage Decisions persist, so reopening the tray restores the findings list with prior decisions, tallies, and progress intact, focused on the next unreviewed finding. ## 4. Layout and components ### 4.1 Tray * Right-hand tray; opening **squeezes the page** rather than overlaying it, so markers stay visible alongside their findings. * Header: "AI Content Review — N suggestions on this page", review timestamp, close button. ### 4.2 Filter chips * One chip per criterion present on the page, letter- and color-coded, toggling that criterion's cards **and** its markers together (marker side owned by the sibling annotation document). ### 4.3 Suggestion cards * One card per finding: criterion label, finding title, rationale, and a **Suggested change** diff — current text struck through, suggested text below. * Card states mirror the decision (see §5) with a status chip ("To review", "✓ Accepted", "✕ Ignored", "⚑ Reported"). ### 4.4 Decision actions * **Accept**, **Ignore**, **⚑ Report** (the suggestion is inappropriate; feedback about the rule/agent rather than the content). After a decision the card's actions collapse to a single **Undo**. ### 4.5 Inline editing of the suggested text * A pencil affordance on the "after" text switches it to a **plain-text inline editor** (no formatting UI). * Save (✓ button or Cmd/Ctrl+Enter) commits; Revert (↺ button or Esc) restores the previous text. * An edited suggestion is tagged **"✎ Edited"**, and the edited text becomes the suggestion — it is what Accept records and what the apply step will present. ### 4.6 Progress footer * "N of M reviewed" with a percentage bar, plus running tallies of accepted / ignored / reported. * When every finding is decided, a **persistent completion CTA** appears — "Task list complete → Apply the changes" — opening the edit form (step 2). It stays visible even if a later Undo drops the count below 100%. ## 5. States ### 5.1 Tray states | ID | State | Trigger | Visible appearance | |----|-------|---------|--------------------| | T1 | Intro | First open after a run | Two-step explanation + "Start improvement plan" CTA | | T2 | Triage | CTA clicked, or returning mid-triage | Filter chips, suggestion cards, progress footer | | T3 | Complete | Every finding decided | Completion note + persistent "Apply the changes" CTA (survives later Undos) | ### 5.2 Card states | ID | State | Trigger | Visible appearance | |----|-------|---------|--------------------| | C1 | To review | Default | Full card with Accept / Ignore / Report | | C2 | Accepted | Accept | "✓ Accepted" chip, actions collapse to Undo | | C3 | Ignored | Ignore | "✕ Ignored" chip, actions collapse to Undo | | C4 | Reported | Report | "⚑ Reported" chip, actions collapse to Undo | | C5 | Editing | Pencil on the "after" text | Inline editor with save/revert | | C6 | Edited | Saved edit | "✎ Edited" tag on the suggestion; decision actions unchanged | ## 6. Interactions ### 6.1 Deciding Accept / Ignore / Report records the decision, updates tallies and progress, and **auto-advances** focus to the next unreviewed finding, scrolling the page to its marker. Undo reverts a decision and restores the card's actions. ### 6.2 Card ↔ marker sync Clicking a card activates it and scrolls the page to its marker; clicking a marker activates its card (opening the tray if closed). Hover states mirror in both directions. ### 6.3 Filtering Toggling a criterion chip hides/shows that criterion's cards and markers; progress counts remain based on all findings, not the filtered subset. ### 6.4 Editing a suggestion Pencil → edit in place → save (✓ / Cmd-Ctrl+Enter) or revert (↺ / Esc). Editing does not itself record a decision; the editor still chooses Accept / Ignore / Report. ### 6.5 Closing Esc or the close button closes the tray; the thermometer button reflects the closed state. Nothing is lost — see §7. ## 7. Persistence * Decisions (including edited suggestion text) persist with the review run: the task list survives closing the tray, navigation, and sessions, and is the input to the apply step. * Re-running the review replaces findings and clears decisions (consistent with #3585828 re-run semantics). ## 8. Edge cases * **Unanchored finding** (location no longer resolvable): its card still appears, flagged as unanchored, and is fully triageable; card→marker scroll is disabled. * **All findings ignored/reported:** completion CTA still appears; the apply step will present an empty plan (its handling is owned by the apply document). * **Single finding on the page:** intro state still shows; progress reads "0 of 1". * **Filtered-out unreviewed findings:** auto-advance skips hidden cards but completion requires deciding them (chips show which criteria still hold unreviewed items). ## 9. Data and API surface (referenced, not specified here) This functional doc does not name or assume specific entity types, fields, or method signatures. What this surface needs: * Decision storage per finding: state (accepted / ignored / reported), edited suggestion text, timestamps — readable by the apply step. * Report decisions queryable for rule-improvement follow-up (which rules get reported most). ## 10. Nice-to-have / future scope * **Accept all** — debated May 22 and deliberately excluded from v1: per-finding decisions keep granularity that feeds accuracy data; revisit once real usage shows whether it's missed. * Keyboard navigation between cards (arrow keys) as a first-class affordance. * Filter-state memory across sessions. ## 11. Acceptance criteria The feature is functionally complete when an editor can, on a reviewed page: 1. Open the tray from the thermometer and see the intro state on first open, with the two-step explanation and Start CTA. 2. See one card per finding with criterion, title, rationale, and a before/after diff. 3. Decide each finding (Accept / Ignore / Report), watch tallies and progress update, and be auto-advanced to the next unreviewed finding. 4. Undo any decision and see counts and the card's actions restored. 5. Edit a suggestion's replacement text inline, save or revert it, see the "✎ Edited" tag, and have the edited text be what Accept records. 6. Filter by criterion and see cards and markers toggle together. 7. Reach 100% reviewed and use the persistent "Apply the changes" CTA to open the edit form — including after a subsequent Undo. 8. Close and reopen the tray (or leave and return) with all decisions and progress intact. ## 12. Open questions * **"Report" label and semantics** — renamed from "Inappropriate" in the v2 export; confirm the final verb and what Report triggers downstream (notify rule owner? counter on the rule?). * **Mobile / narrow viewports** for the squeezed-page layout. * **Filtered unreviewed findings** — should completion be reachable while some criteria are hidden (current answer: no; confirm)? * A11y pass: focus order for auto-advance, editor announcement, chip toggle semantics. ## Screenshorts Filters show/hide marker elements. Clicking the marker or the suggestion card scrolls to the marker/card. {width="497" height="354"} {width="488" height="341"} You can edit the suggestion with inline edit form. sdfdsfds {width="368" height="600"} Accept / Ignore / Flag Each item updates the progress bar and markers below {width="367" height="600"} When all suggestions are accouned for (Accepts / Ignored / Reported) Apply changes button appears (Linking to another workflow spec (Apply Improvement plan) ## Claude Design / Video (Full workflow) https://zoom.us/media/share/VyxVIvnSRYeej3U8lsSySQ?module=clips&product=video-center [Plan Improvements v3 (standalone).html](/uploads/53b575a9f44a61907d35242fa38c59fc/Plan_Improvements_v3__standalone_.html)