Revising a document with AI

Most of the value is in the second pass. Describe the change you want in the document’s AI tab, and Workover AI proposes it as tracked suggestions that you accept or reject. It works on what is already there rather than starting over, so the parts you liked survive.

Before you start:

Your workspace needs an AI provider chosen under Settings > AI, either Workover AI (included with a paid plan) or Your own key. See Choose who provides Workover AI.
You need to be a workspace member with edit access. Guests do not get the Edit panel or the AI actions.

Ask for a change

Open the document and select Edit panel in the document toolbar, then the AI tab (the arrow-pointer icon).
Select Iterate.
Type your instruction in Tell the AI how to change this doc… and press Enter.

Iterate always works on the whole document. Selecting text first does not narrow it.
When it finishes, the panel shows a one-line summary of the change, and the edits appear in the document as tracked suggestions. Continue with Review what comes back.

The Iterate conversation is saved with the document, so you can come back later and ask for the next change in the same thread.

If the project has a linked code repository and your AI provider can read repositories, Iterate can check the code while it revises. That makes an instruction such as “the parameter names in the API section are out of date” something it can verify rather than guess. See Grounding drafts in your code repository.

Write instructions that work

Useful instructions are specific about the problem, not just the target:

“The opening buries the point. Lead with the failure it prevents.”
“Cut this to about 600 words. Lose the history section, keep the examples.”
“The API section assumes people know what a webhook is. They don’t.”
“Too salesy from ‘Why teams choose us’ onwards. Make it factual.”

Vague instructions (“make it better”, “improve the flow”) produce vague edits.

Review what comes back

Nothing from Iterate is applied until you accept it. The review bar at the top of the document shows how many changes there are to review. When there is more than one, step through them with the previous and next arrows. To resolve them all at once, select Accept all or Reject all.

Accepting changes one at a time is usually right, because a revision is rarely wholly good or wholly bad. Rejecting everything leaves the document as it was, so a revision that misses costs nothing. For how suggestions work in general, see Comments and suggestions.

Quick edits to a selection

Selecting text shows a menu with four fixed actions: Improve, Shorten, Expand and Fix grammar. These do not take an instruction.

Warning: These actions replace the selected text immediately, without a suggestion to review, and Suggesting mode does not change that: it tracks what you type, not these actions. When you want to review a change before it lands, use Iterate instead.

When to start over instead

If two rounds have not moved it, the brief was wrong rather than the draft. Go back to the brief and restate the audience and the outcome, which is usually what was missing.

Publishing

You cannot publish while suggestions are unresolved. The publishing tab of the Edit panel (WP, Webflow or Mintlify, depending on the project) shows how many suggestions are pending and asks you to resolve them first. On WordPress it also explains why: publishing now would put the tracked changes, including the replaced text, on your live site.