Skip to content

Suggestions and the improvement plan

A completed review can return suggestions. Each one is stored as its own append-only Suggestion entity referenced from the Review Record.

Suggestion types

Plugin ID What it does
Text replacement text_replace Replaces the passage the suggestion quotes in a text field with the suggested text. The rest of the field is left as it was. Needs a target field name.
Text removal text_remove Removes the passage the suggestion quotes from a text field.
General recommendation general_recommendation Free text not tied to one field, for structural or cross-field findings.

Other modules can add types. See Suggestion plugins.

Applying a suggestion

A text replacement or removal suggestion carries an Apply button. Applying changes only the quoted passage, saves the content (as a new revision, where the content type has revisions) and stamps the suggestion with who applied it and when.

Apply is refused, with the reason, and nothing is changed when:

  • the quoted text is no longer in the field, or occurs more than once, because the content was edited after the review;
  • the AI did not copy the quoted text as it is stored, so it cannot be found;
  • the change would break the formatting around it, or drop a link, an image or embedded media;
  • the target is not a text field.

In those cases make the change by hand. For a field with several values, the suggestion may name the item (field_notes:1) so that a sentence repeated in two items can still be applied.

Show proposed change opens a side-by-side diff of the current and suggested values.

A suggestion with Show proposed change expanded, showing the current value in red beside the suggested value in green

General recommendations have no Apply button. They describe something to do by hand.

Triage

Every suggestion also carries a decision, independent of whether it was applied:

Action Result
Accept The suggestion joins the improvement plan for that entity.
Ignore The suggestion is marked decided and stays out of the plan.
Undo Clears the decision, and clears any tick on the plan item.

Triage is available in the result dialog on the review tab and in the suggestion cards of the top bar panel. Both need the Run AI content reviews permission.

A suggestion after acceptance, showing the Accepted stamp and an Undo link

The top bar panel gathers every suggestion on the page into one triage tray, with a chip per criterion and a progress footer.

The triage tray in the side panel: criterion chips, suggestion cards with Accept and Ignore, and a footer reading 2 of 7 reviewed

The improvement plan

The improvement plan is the read side of triage: for one entity, every suggestion accepted across all of its criteria, taking only the newest record per criterion. It renders as a checklist in the AI Review section of the entity edit form sidebar.

flowchart LR
    Result[Review result] --> Decide{Decision}
    Decide -->|Accept| Plan[Improvement plan]
    Decide -->|Ignore| Out[Left off the plan]
    Plan --> Tick[Ticked off]
    Tick -->|stays on the list| Plan

The entity edit form sidebar: the Content Review summary with a gauge per criterion, and the Improvement plan checklist below it

Ticking an item off marks it done and keeps it on the list, so you can see what you already carried out and untick an item if you got ahead of yourself. The section title reports how many items are still open rather than how long the list is.

The plan refreshes in place when a suggestion is accepted in a result dialog opened over the same edit form, so the checklist stays current without a reload.

The plan lives on the edit form only. Working through it means editing fields, so the top bar panel deliberately does not carry a second copy.

Append-only, with one exception

Review Records and Suggestions cannot be edited or deleted. This is enforced both by their access control handlers and by hook_entity_access().

Append-only governs what a user may rewrite: nothing the AI produced is ever changed or removed. The system still records what the editor did with a suggestion, on the suggestion itself: applied_at and applied_by, and the triage fields decision, decided_at, decided_by, checked_off_at and checked_off_by. Those writes go through the entity's own setters from a controller, never through an entity form.

All state-changing endpoints (run, poll, pause, heartbeat, apply, decide, check off) are POST routes requiring a CSRF token minted server-side. A review costs provider budget, so none of them is reachable by a GET.