Revising Documents

When you want to refine a markdown document with targeted AI assistance, use the revise workflow. Instead of rewriting text yourself, you highlight specific passages, describe what should change, and let Claude propose edits that you can accept, reject, or modify. This is especially useful after creating a plan, but works with any markdown document open in the Atelier editor.

Prerequisites

A markdown document open in the Atelier markdown editor
Atelier extension with the Revise Skill installed
Claude Code installed

Steps

Open a markdown document in the Atelier markdown editor.

There are several ways to open the editor:
- From the Kanban board — Click on the file name of any item to open it directly in the Atelier markdown editor.
- From an open tab — Right-click the file name in the tab bar and select Reopen Editor With…, then choose Atelier Markdown Editor.
- From the file explorer — Right-click a markdown file and select Open With…, then choose Atelier Markdown Editor.
The editor displays the document with a toolbar at the top and a sidebar on the right. You can open any markdown file — plans, tasks, or standalone documents.
Select a passage of text you want to revise.

Click and drag to highlight the text in the editor. This can be a single sentence, a paragraph, or any contiguous block of text.
Click the highlight button in the editor toolbar, or press ⌘ + H.

A yellow highlight appears over the selected text in the editor, and the sidebar opens to show an annotation card for this passage.
Type your feedback in the sidebar and press Enter to save.

Describe how the passage should change — for example, “make this more concise,” “add an example here,” or “this contradicts the section above.” Your feedback tells Claude what to fix and why.
Repeat steps 2–4 for any additional passages you want revised.

You can annotate as many passages as needed before launching the agent. Each annotation gets its own yellow highlight in the editor and its own card in the sidebar.
Click the button in the bottom-right corner of the editor.

Atelier opens a new terminal tab and sends a prompt to Claude Code using the Revise Skill. The prompt includes the document content, all annotations, and their positions.
Wait for the agent to finish processing your feedback.

The terminal shows Claude working through each annotation. When it finishes, the editor updates with suggested edits.

Reviewing suggestions

Observe that your yellow highlights have turned into green suggested edits.

Each annotation now shows the agent’s proposed changes in the document. The sidebar cards update to include the agent’s response describing how it addressed your feedback.
Page through annotations in the sidebar.

Each annotation has its own page in the sidebar. When you click on an annotation or switch to a different page, the editor scrolls to the part of the document where that suggested edit was made. A bright green highlight appears in the gutter on the left side of the editor to show which lines are linked to the selected annotation.
Read the agent’s response for each annotation.

The sidebar shows both your original feedback and the agent’s explanation of the changes it made.

Resolving edits

You have three levels of granularity for accepting or rejecting suggested edits, from coarsest to finest.

Accept all at once:

Click the button in the bottom-right corner of the editor.

All suggested edits are accepted simultaneously. The green highlights clear and the changes become part of the document.

Per annotation:

Locate the and buttons at the top of each annotation card in the sidebar.

Each card has a checkmark (accept) and an X (reject). The edits linked to a given annotation are indicated by bright green highlights in the gutter on the left side of the editor.
Click the checkmark to accept or the X to reject that annotation’s edits.

Accepting applies all edits linked to that annotation. Rejecting reverts the affected passages to their original text.

Per individual edit:

Click on a specific green-highlighted edit in the document.

Accept and reject buttons appear for that individual edit. This is independent of the sidebar annotation controls — you can accept some edits within an annotation while rejecting others.
Click and button for that specific edit.

The edit is applied or reverted without affecting any other edits, even those belonging to the same annotation.

Follow-up revisions

Reply to the agent’s message on an annotation card in the sidebar.

Instead of rejecting an edit, you can type additional feedback or clarification as a reply. This creates a new message in that annotation’s conversation thread.
Add follow-up feedback to as many annotations as needed.

The Revise button reappears in the bottom-right corner whenever there are unprocessed follow-up messages. New messages are not sent to the agent until you click it.
Click the button to send your follow-up feedback.

Atelier sends the new messages to the existing terminal session. The agent processes your follow-ups and proposes revised edits.
Review and resolve the new suggestions using the same accept/reject workflow described above.

You have now iteratively refined a markdown document using targeted AI-assisted revisions, with full control over which suggestions to accept, reject, or modify at any level of granularity.