review-mode

Review Mode Skill

Overview

Review Mode is a VS Code extension that renders Markdown files in a read-only WebView panel with threaded annotation support. Users can highlight lines, add comments, set priorities, and track statuses — all stored as JSON alongside the file.

This skill teaches you how to:

1. Open any .md file in Review Mode
2. Read user feedback from annotations
3. Iterate on the document based on that feedback
4. Manage the annotation lifecycle (resolve, clarify, reject)

The skill is agent-agnostic — it works regardless of how the document was created.

Prerequisite: The review-mode MCP server must be configured in your MCP client settings. All operations use MCP tools — no CLI scripts or direct file reads are needed.

Command trigger: Treat /review-mode as an explicit user command to open the relevant Markdown plan/document in Review Mode via MCP (open_review), then confirm in chat that the file was created (if applicable) and opened in Review Mode.

MCP Server Installation & Troubleshooting

If the plugin is installed correctly, the MCP server configuration is already registered (via .mcp.json). However, the review-mode-mcp executable itself must be installed on the system. If MCP tool calls fail with "tool not found", "server failed to start", or similar connection errors, the executable is likely missing.

Diagnosis: Run in the shell:

review-mode-mcp --version

If the command is not found, the MCP server is not installed.

Installation: The MCP server is distributed as a Python package and installed via uv:

1. Ensure uv is installed. If not, install it following the uv installation guide.
2. Install the MCP server:

   uv tool install review-mode-mcp
   

3. Verify the installation:

   review-mode-mcp --version
   

4. After installation, restart or reconnect the MCP client so it can pick up the new executable.

Important: If MCP tools fail unexpectedly, always check review-mode-mcp --version first before assuming a configuration issue.

Tool Overview

The review-mode-mcp server provides the following tools:

• open_review: Opens a file in Review Mode inside the editor.
• get_annotations: Returns the full array of annotations for a file.
• update_annotation: Updates the status or adds an agent reply to an annotation.
• list_reviewed_files: Lists all files in the workspace that have reviews.
• get_review_summary: Returns summary metadata for a file's review (counts, dates).
• create_annotation: Creates a new annotation on a specific line as the agent.

Note on workspace parameter: While listed as optional in some schemas, it is highly recommended (and sometimes mandatory depending on server config) to provide the workspace parameter with the absolute or relative path to the root of the project to ensure the MCP server resolves paths correctly.

---

How to Open Review Mode

Use the open_review MCP tool:

open_review(
  file_path="relative/path/to/file.md",
  workspace="/path/to/project/root" # Recommended
)

This opens the file in Review Mode inside VS Code (or whichever editor the MCP server is configured for).

After opening, print a brief message in chat:

📋 The plan is ready for review in Review Mode.

Do NOT print the plan content in chat. The user will read it in the Review Mode panel.

---

How to Read Feedback

When the user says they've added comments, or asks you to iterate on a plan, you MUST proactively read annotations using the MCP tools. Never ask the user to paste their annotations.

Step 1 — Get annotations

get_annotations(
  file_path="relative/path/to/file.md",
  workspace="/path/to/project/root"
)

This returns the full annotation array from the latest revision.

Step 2 — Summarize

Print a brief summary:

📝 Found N annotations (X open, Y in-progress, Z resolved).

Step 3 — Filter actionable annotations

Only process annotations where status is "open" or "in-progress". Ignore "resolved" and "wont-fix".

---

Annotation Format

Each annotation returned by get_annotations has this structure:

{
  "id": "cc1rclk",
  "startLine": 3,
  "endLine": 3,
  "textPreview": "The line of text this annotation refers to",
  "priority": "none",
  "status": "open",
  "thread": [
    {
      "id": "2wu1xvj",
      "text": "User's comment about this line",
      "createdAt": "2026-04-28T17:10:19.928Z"
    }
  ]
}

Fields:

Field	Description
id	Unique identifier for the annotation
startLine / endLine	Line range in the markdown file (1-indexed)
textPreview	The text content at the annotated line(s)
priority	One of: none, low, medium, high, urgent
status	One of: open, in-progress, resolved, wont-fix
thread	Array of messages (the comment thread)

Each message in thread[] has:

Field	Description
id	Unique message identifier
text	The message content
createdAt	ISO 8601 timestamp

---

How to Respond to Feedback

For each actionable annotation (status open or in-progress), decide one of three outcomes:

1. Fully addressable — Resolve it

Edit the .md file to implement the change, then mark resolved:

update_annotation(
  file_path="relative/path/to/file.md",
  annotation_ids=["cc1rclk"],
  status="resolved",
  message="Implemented the requested change",
  workspace="/path/to/project/root"
)

2. Needs clarification — Ask the user

update_annotation(
  file_path="relative/path/to/file.md",
  annotation_ids=["cc1rclk"],
  status="in-progress",
  message="Which kind of description do you want? Verbose, concise, etc.?",
  workspace="/path/to/project/root"
)

3. Won't implement — Explain why

update_annotation(
  file_path="relative/path/to/file.md",
  annotation_ids=["cc1rclk"],
  status="wont-fix",
  message="Not feasible due to API limitations",
  workspace="/path/to/project/root"
)

Bulk resolve

Pass multiple IDs at once:

update_annotation(
  file_path="relative/path/to/file.md",
  annotation_ids=["id1", "id2", "id3"],
  status="resolved",
  message="All comments addressed",
  workspace="/path/to/project/root"
)

Summary Table

Scenario	Action on .md file	MCP call
Fully addressable	Implement the change	status="resolved"
Needs clarification	No change (or partial)	status="in-progress", with question in message
Won't implement	No change	status="wont-fix", with reason in message

The message is automatically prefixed with [AGENT] and added to the annotation's thread.

---

Utility Tools

You can use these additional tools to manage the review workflow:

Discover files under review

list_reviewed_files(workspace="/path/to/project/root")

Returns an array of files that have reviews, along with their revision_count, total_annotations, open_count, etc. Useful if you're not sure which file the user wants you to look at.

Get a quick summary

get_review_summary(file_path="relative/path/to/file.md", workspace="/path/to/project/root")

Returns metadata about a file's review state without pulling down the entire annotation array.

Create an annotation

If you need to leave a comment or question on a specific line of the file for the user to see:

create_annotation(
  file_path="relative/path/to/file.md",
  line=42,
  message="Should we consider refactoring this section?",
  priority="medium",
  status="open",
  workspace="/path/to/project/root"
)

---

How to Submit the Updated Plan

After processing all actionable annotations:

1. Write the updated .md file to disk (same path as the original).
2. Mark annotations as resolved using update_annotation (see above).
3. Re-open Review Mode to refresh the panel:

   open_review(file_path="relative/path/to/file.md")
   

   The extension will detect the file change and automatically create a new revision with migrated annotations.
4. Print a brief status message in chat: 📋 Plan updated and ready for review. N comments resolved, M need your input.

---

Iteration Flow

The user will trigger iteration with one of two intents:

Intent A: "Refine with my comments" / "Update the plan"

1. Fetch annotations: get_annotations(file_path=<file>)
2. Process each actionable annotation (resolve, clarify, or reject)
3. Write updated .md file
4. Resolve annotations: update_annotation(file_path=<file>, annotation_ids=[...], status="resolved", message="Done")
5. Re-open Review Mode: open_review(file_path=<file>)
6. Print status message
7. Say: "I've updated the plan. Take a look and let me know if you have more feedback."

Intent B: "Implement comments and proceed" / "Finalize and implement"

1. Fetch annotations: get_annotations(file_path=<file>)
2. Process each actionable annotation (resolve, clarify, or reject)
3. Write updated .md file
4. Resolve all: update_annotation(file_path=<file>, annotation_ids=[<all IDs>], status="resolved", message="All addressed")
5. Re-open Review Mode: open_review(file_path=<file>)
6. Print status message
7. Confirm: "The plan has been finalized. Ready to proceed with implementation?"

When there's nothing left to review

After a round where no annotations have status open and no new feedback was given, gently ask:

"The plan looks solid with no outstanding comments. Would you like to proceed with implementation, or do you want to review it further?"

Do NOT rush the user into implementation. Wait for explicit confirmation.

---