**Status:** Draft for review **Author:** Aidan Foster --- ## 1. Purpose Before an editor can triage AI feedback on a page, something has to produce that feedback. A review run fans out to multiple review agents (one per configured criterion — examples could include SEO, accessibility, readability, tone and voice, structure, factual/citations, inclusive language, or legal/compliance), each of which reviews the rendered page and emits scored, tagged findings. This document specifies the **run experience in the front-end view mode of a single node**: the trigger, the visible progress while agents run, and the **scoring thermometer** that summarizes the completed run in the admin toolbar. Unlike the list-display pill widget (#3585821), which is a snapshot of stored results with no live state, this surface is exactly where the editor watches a run happen. Anchoring findings onto the rendered page and triaging them are sibling documents; this one ends when a run is complete and its findings are stored. ## 2. Scope ### In scope * The scoring thermometer button in the view-mode admin toolbar (segmented fail / warn / pass counts, aggregate score, open/closed states). * Triggering a review run from view mode (first run and re-run). * The run model: independent per-criterion agent runs with individual progress. * The run-progress sidebar, reusing the node edit form's review sidebar UI. * Live per-criterion recommendations counters during the run. * The overall run-completion component, separate from any individual criterion row. * The contract for what a completed agent run emits (consumed by the marker-anchoring document). ### Out of scope * Rendering findings on the page (markers) — sibling document. * Triaging findings (accept / ignore / report) — sibling document. * Applying changes on the edit form — sibling document. * The list-display pill widget and its states — #3585821. * Bulk runs across many content items — future scope of #3585821. * Provider-side prompt design per criterion; queue worker behavior. ### Assumptions * The Drupal AI module is available and configured with at least one provider. * Some persistent storage exists per entity for per-criterion review results. The exact data model is **not assumed by this document** and is owned by the implementation specs that follow. * For this milestone, AI Content Review operates **independently of the Context Control Center (CCC)**. Criterion definitions, labels, and rules live within the module's own configuration. * The threshold model (pass threshold required, optional warn threshold, direction flag) is the one specified in #3585821 §7, including its architecture flag: **that model does not yet exist in the module and is a prerequisite here too.** ## 3. Entry workflows ### Workflow A — Page with a prior review The node has stored results from a prior run. The toolbar thermometer renders the most recent tally (e.g. 2 fail / 2 warn / 6 pass, 72%). Clicking it opens the review tray; a re-run affordance is available. ### Workflow B — Page never reviewed No stored results exist. The thermometer renders an un-scored placeholder state with a run affordance (consistent with the unscored state in the `edit_blog_unscored_v02.html` prototype). ## 4. Layout and components ### 4.1 Scoring thermometer (toolbar button) * Lives in the view-mode admin toolbar (Gin). One segmented bar: fail (red) / warn (yellow) / pass (green) counts sized proportionally, numeric labels always present, plus the aggregate percentage beside it. * Numbers carry the truth even when color is not perceivable (same hard rule as #3585821 §4.1). * The button toggles the review tray; it reflects open (pressed) and closed states. ### 4.2 Per-criterion thermometer rows * **Each agent run gets its own thermometer.** The row shows that agent's current score against its configured fail / (optional) warn / pass thresholds, **updating live as the run progresses**; beside it, a pulsing "Recommendations" counter increments as suggestions are found (e.g. Tone and voice: 4 items of feedback). * On completion the counter equals the number of feedback markers for that criterion's category in the triage phase, so the progress UI and the marker overlay always agree. * Reuses the threshold-bar component from the May 8 single-node review issue. ### 4.3 Overall completion component * **Total review completion is a separate component** from the per-criterion rows: a progress bar with "N of M reviews complete." Partial completion stays legible while agents are still running. ### 4.4 Progress sidebar * Render time per agent is unknown and potentially long, so v1 keeps the progress UI intentionally minimal: **reuse the node edit form's review sidebar — the same UI shown when you run all criteria the first time** (as in the `edit_blog_unscored_v02.html` prototype). While a run is in progress the sidebar lists each agent run with its state, each running row showing the live score and pulsing recommendations counter described in §4.2. ## 5. States | ID | State | Trigger | Visible appearance | |----|-------|---------|--------------------| | S1 | Unscored | No stored results for any criterion | Placeholder thermometer, run affordance | | S2 | Running | A review run is in flight | Sidebar lists agent runs as queued / running / complete / failed; running rows show live score + pulsing counter; overall completion bar advances | | S3 | Completed | Every agent run finished (successfully or not) | Toolbar thermometer shows the final fail/warn/pass tally and aggregate score | | S4 | Partial failure | One or more agent runs failed | Failed criteria shown as failed in the sidebar and excluded from the aggregate; the rest of the run is unaffected; retry affordance per failed criterion | * Agent runs execute independently and complete independently; a criterion that takes 60 seconds must not block one that takes 5. * Re-running replaces prior results (per the May 8 decision; history is a future enhancement). * **On completion.** Each agent run's output is a set of findings tagged with criterion, severity, rationale, suggested change, and a location reference into the rendered page (consumed by the marker-anchoring document). ## 6. Interactions ### 6.1 Toggle the review tray Clicking the thermometer opens/closes the tray; Esc closes. The button exposes an accessible label carrying the same counts and score as the visual. ### 6.2 Run / re-run From S1, the run affordance starts a full run (all configured criteria). From S3/S4, re-run replaces prior results; retry on a failed criterion re-runs only that agent. ### 6.3 During the run Progress events update the sidebar rows and overall completion bar as they arrive; the editor can keep reading the page while the run proceeds. ## 7. Threshold model Identical to #3585821 §7 — the widget consumes per-criterion pass (required) / warn (optional, strictly lower) thresholds and a direction flag. > **Architecture flag (shared with #3585821).** The threshold model does not yet exist in the module and is a prerequisite for implementing this document as specified. ## 8. Edge cases * **One criterion configured.** A single-segment thermometer; aggregate score is redundant (mute or hide, consistent with #3585821). * **Editor navigates away mid-run.** The run continues server-side; returning to the page re-enters S2 with current progress. * **Stale criteria** (rules changed since last run). Consistent with #3585821 §5.1: per-criterion invalidation, rendered as not-reviewed until re-run. * **All agents fail.** S4 with no aggregate score; run affordance surfaces as retry. ## 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 from whatever is built: * A way to trigger a full run, and a single-criterion retry, for one entity. * Per-agent progress events (state transitions plus incremental suggestion counts and current score) the sidebar can consume — mechanism (polling vs. streamed) is an implementation decision. * Read access to the completed tally (per-criterion status, counts, aggregate score). * Findings storage keyed by run, criterion, and location reference; replaced on re-run. ## 10. Nice-to-have / future scope * Run history (compare against prior runs) — explicitly deferred May 8. * Reviewing a single criterion on demand as a first-class affordance (open question carried from May 8). ## 11. Acceptance criteria The feature is functionally complete when an editor can, on a node's view mode: 1. See the un-scored state with a run affordance on a never-reviewed page. 2. Start a run and watch each criterion progress independently — live score against thresholds and a pulsing recommendations counter per running row — without any criterion blocking another. 3. See overall completion ("N of M reviews complete") as a component separate from any criterion row. 4. See the completed toolbar thermometer with fail / warn / pass counts readable as numbers, plus the aggregate score. 5. Toggle the review tray from the thermometer, with open state reflected on the button. 6. See a failed criterion excluded from the aggregate with a retry affordance, while other criteria complete normally. 7. Re-run and have prior results replaced. 8. Verify the completed per-criterion counter equals that criterion's marker count in the triage phase. ## 12. Open questions * **Running-row treatment.** Live score against thresholds with pulsing counter (current proposal) vs. counts-only until the agent completes (as shown in the `t1_04` mock screenshot). * **Aggregate score formula.** Average of criterion scores vs. weighted. * **Progress event mechanism.** Polling, SSE, or streamed response — shared question with the May 8 issue. * **Failure/retry UX** for a single failed agent run. * Validate thermometer states against the three task scenarios in the May 8 parent issue. ## 13. Screenshots {width=900 height=470} Try closed (Note there should not be markers on the content yet unless there is a past run) {width=900 height=471} Click score thermometer opens side try. Click "Start improvement Plan" to kick off agents review {width=900 height=497} In progress runs "pulse" (but have their previous scores) only. Comment counter increases as each finishes. (Can it update as they find them???). When complete confirm and move to next section. ## 14. Video https://zoom.us/media/share/VyxVIvnSRYeej3U8lsSySQ?module=clips&product=video-center ## 15. Claude design — standalone HTML export [Plan Improvements v3 (standalone).html](/uploads/f297fc8f49b60d277d4049ea8dc8a203/Plan_Improvements_v3__standalone_.html) * (Full demo shows more scope than just this step). --- _Sources: AI review working sessions May 15 and May 22, 2026; AI review sync June 1, 2026. Comp explorations done in Claude Code; walkthrough video to be attached._