Everything here applies to reports, code reviews, decision records and briefs too. The buttons name the document type, for example Approve report or Approve code review.
Reading and editing
A document opens for reading. This is where you review: comment, pick options, answer questions and tick checklists. The page updates live while you read, so new comments, ticks and step progress appear without a reload. Avatars at the top show who else has the page open.
If you can edit the document, an Edit button sits at the top of the page. It opens the editor, and several people can edit at once. Click Done editing to go back to reading. To work on the raw markdown, open the ⋯ menu and choose Edit as markdown.
Your edits change the working copy. They don't create a version and don't ask anyone to review. When the agent next calls get_feedback, it receives a diff of what you changed since its last version, and it is told to respect your edits.
Comments
You can comment in three ways:
- On a block. Use the comment button beside any paragraph, heading, step, decision, question, checklist or other block.
- On highlighted text. Select words in the text and click the Comment button that appears. The comment quotes what you selected.
- On the whole document. Use Comment on the document below the text.
Comments sit in the margin next to the block they belong to. Reply in a thread, and Resolve it once it's handled. Resolved threads are hidden; Show resolved brings them back. If the block a comment was on is removed in a later version, the comment moves to the general list and says it was on a removed block.
Agents reply to comments and resolve the ones they've dealt with. Unresolved comments go to the agent with your review.
Right-click a comment, or use the ⋯ beside its time, for Reply, Copy link, Resolve thread or Reopen thread, and Delete comment on your own comments. Deleting asks first, removes the comment for everyone, and removes the thread too if it was the only comment. A copied link opens the document with that thread showing.
Block menus
While reading, right-click any block, or use the ⋯ under its comment button, for:
- Comment, and Ask agent about this, which starts a comment addressed to the agent that wrote the document. It answers when it next reads feedback.
- Copy link to block (Copy step link on a step). The link opens the document scrolled to that block.
- Copy as markdown, the block in the same markdown agents write.
- Clear my choice on a decision you picked, and Clear my answer on a question you answered.
- On a step, View PR and the other links the agent attached to it.
Links inside the text, selected text and the editor keep your browser's own menu. From the keyboard, tab to the block's ⋯, or press Shift+F10 or the Menu key while focus is inside the block; on a phone or tablet, long-press the block.
Decisions
A decision lists options, each with a short explanation. One may be labelled Agent recommends. That label is advice only: nothing is chosen until you choose. Pick an option to make the decision; Clear choice undoes it.
Once picked, the decision shows who chose. If the agent publishes a new version later, your pick is kept.
Questions
A question block asks you something. Suggested answers appear as buttons, and there is a box to answer in your own words. Questions marked Required must be answered before you can approve. Agents can also add a question while they work, which notifies reviewers and appears at the end of the document.
Checklists
Tick or untick checklist items. The agent sees which items are ticked.
Before you can approve
When a document is waiting for your review and has decisions or required questions, a line headed Before you can approve appears above the text. It lists each decision as made or open, and the required questions as answered or still open. Click an item to scroll to it.
The bottom bar repeats the count, for example "Answer 2 items to approve".
Approve or request changes
The bar at the bottom of the page shows what approving will do, then two buttons.
Approve. Accepts the current version. For a plan, an agent with Publish and run access can start work. Everyone else's review requests for this document are closed.
Request changes. Opens a dialog titled "Request changes on vN?". A note is required: say what needs to change and why. The agent gets the note and every open comment in one message. The document moves to Changes requested, and the agent revises it and submits a new version.
Only people with the Reviewer role or above can approve or request changes. In your personal workspace that's you. See Members and roles.
Approving with items open
If decisions or required questions are still open when you click Approve, planpage asks "Approve with N items still open?" and lists them. You can:
- Go back and decide. Closes the dialog so you can finish the open items.
- Approve anyway. Approves the version as it is.
Approving anyway is recorded. The approval reads "Approved by you with items open", and get_feedback tells the agent that you approved with items open and which ones they were. For a plan, the agent starts without your answers and makes those choices itself. Deciding first takes a minute and keeps the plan yours.
Other actions
The ⋯ menu at the top of the page has:
- Export markdown. Downloads the working copy as a markdown file.
- Compare versions. See Versions and changes.
- Follow or Unfollow. Adds the document to, or removes it from, the Following tab of your Inbox.
- Submit for review… and Save a version…, if you can edit.
- Move to. For reviewers: set the status by hand to In progress, Done, Abandoned or Draft.
- Archive… For owners and admins. Archived documents leave the project's lists and can't be edited until restored. Links keep working.
- Move to Trash… For owners and admins. The document disappears for everyone and is deleted for good after 30 days unless restored. See Delete a document.
Owners and admins also see Share, covered in Sharing.