Human Reviewer Guide

Review plans, designs, and prototypes
without losing context.

This guide covers the full Revi workflow for human reviewers: preparing the workspace, navigating the interface, leaving anchored comments, resolving feedback, archiving review rounds, and checking what agents will actually receive.

Open Demo Markdown Source

Workspace Setup

Revi auto-discovers review items from the workspace directory. Place each file in the right subfolder and it appears in the sidebar automatically on the next refresh.

workspace/ plans/ designs/ prototypes/
plans/ Architecture docs, sprint plans, specs, and any Markdown document you want reviewed with heading anchors and text selection comments.
designs/ Images such as mockups, wireframes, diagrams, and annotated screenshots.
prototypes/ Self-contained HTML files for click-through or step-by-step interactive flows.
Naming File names become display titles, so descriptive names like sprint-1-design.md and ui-mockup-v2.png work best.
You can also upload files through the API if you do not want to copy them into the workspace manually.

Reviewing Items

Opening any item brings you into the split review layout: content in the center, comments on the right, and an optional navigation panel on the left for supported item types.

Plans Markdown plans support a document index, in-page search, quote selection, heading anchors, and active section tracking.
Designs Design files render on a dark canvas with numbered annotation pins. Hovering a matching comment highlights the pin.
Prototypes Interactive prototype flows use a step navigator with per-step commenting and zoom controls for the visual panel.
Review loop Reviewers inspect the artifact, leave precise feedback, and then resolve or archive comments after the issue is addressed.

Leaving Comments

Open the form

Click Add Comment in the comment panel. The form expands beneath the action bar.

Use pre-filled anchors

Action Anchor created
Select text in a plan and click the comment tooltip quote
Click an annotation pin in a design annotation
Click the comment action on a prototype step step

Manual references

If nothing was pre-filled, type a section reference manually, for example ## Architecture. Leave the reference empty to create a general comment that applies to the whole item.

Anchor Types

Every comment can point at a precise location. This makes the review workflow legible for both humans and agents.

section

Link a comment to a Markdown heading such as ## Storage Layer.

quote

Attach feedback to a selected text fragment inside a plan.

line

Point to a specific line number in a document.

annotation

Reference a numbered annotation pin on a design image.

step

Attach feedback to a prototype step in a walkthrough flow.

general

Leave item-level feedback with no single anchor.

Resolve and Archive

Resolve comments

When a comment has been addressed, click Mark resolved. The comment moves from the Open tab to the Resolved tab.

Archive review rounds

Resolved comments stay visible until they are archived. Archiving bundles them into a timestamped batch and clears the active queue for the next review cycle.

Browse archive history

The archive view groups batches by item and preserves the full review history, including author, resolution time, reference, and content.

Agent Export Preview

At the bottom of the comment panel you can expand Agent Export Preview to inspect the structured JSON that agents receive from GET /api/export/{item_id}.

{ "schemaVersion": "1.0", "item": { "id": "plans/sprint-1-design", "type": "plan" }, "openComments": [...] }
Only open comments are exported. Resolved and archived comments are intentionally omitted, so agents only act on unresolved feedback.

Tips

  • Use comments with anchors whenever possible so reviewers and agents both know exactly what the feedback refers to.
  • Use the plan search bar to jump between repeated terms before leaving a broad comment.
  • Hover comment cards to confirm that the reference highlights the correct section, quote, pin, or step.
  • Archive resolved batches regularly so the next review round starts clean.
  • Use the live demo if you want to explain the workflow to teammates before setting up a local environment.