File Review

Unified skill for the file-review plugin. Routes to the correct workflow based on user intent.

Note: The /file-review and /process-comments commands are simple shortcuts for backward compatibility. They trigger the Review and Process workflows below. This skill is the canonical entry point.

Intent Router

Match the user’s request to one of three workflows:

If the intent is ambiguous, use AskUserQuestion:

Install

Quick Install (Homebrew)

brew tap desplega-ai/tap
brew install file-review

Verify: which file-review

Manual Install (from source)

Prerequisites: bun, Rust

git clone https://github.com/desplega-ai/ai-toolbox.git
cd ai-toolbox/file-review
bun install
bun run install:app

This symlinks to ~/.local/bin/file-review. Ensure that’s in PATH.

Troubleshooting

• Command not found: Ensure ~/.local/bin in PATH, restart terminal
• Rust not found: Restart terminal after installing Rust
• Build fails on macOS: xcode-select --install

Uninstall

cd ai-toolbox/file-review && bun run uninstall:app

Review a File

If no path provided

Check for recently created or modified files in the current session:

• Plan files in thoughts/<username|shared>/plans/
• Research documents in thoughts/<username|shared>/research/
• Any markdown files created or updated during the conversation

Propose candidates to the user via AskUserQuestion.

If path provided

1. Verify the file exists and is readable.

2. Check if file-review is installed:

   which file-review
   

   If not found, jump to the Install section above.

3. Launch the GUI:

   file-review "<absolute_path>"
   

   Wait for the process to complete.

   CLI flags: --bg (background), --silent (no comment output), --json (JSON output).

4. Inform the user:

   I've opened file-review for <filename>.
   
   Shortcuts: Cmd+K (add comment), Cmd+S (save), Cmd+Q (quit), Cmd+/ (help)
   

5. After the app closes, it outputs review comments to stdout:

   === Review Comments (N) ===
   
   [abc123] Line 15 (inline):
       "highlighted code"
       -> Comment text here
   

   Present the output, then proceed to Process Comments below.

Keyboard Shortcuts

Process Comments

Comment Format

The file-review tool embeds comments as HTML markers:

Inline comments:

<!-- review-start(ID) -->highlighted text<!-- review-end(ID): reviewer feedback -->

Line comments:

<!-- review-line-start(ID) -->
content spanning
multiple lines
<!-- review-line-end(ID): reviewer feedback -->

ID is an 8-character alphanumeric identifier.

Extraction Patterns

// Inline - captures: [full, id, highlighted, feedback]
/<!--\s*review-start\(([a-zA-Z0-9-]+)\)\s*-->([\s\S]*?)<!--\s*review-end\(\1\):\s*([\s\S]*?)\s*-->/g

// Line - captures: [full, id, highlighted, feedback]
/<!--\s*review-line-start\(([a-zA-Z0-9-]+)\)\s*-->\n?([\s\S]*?)\n?<!--\s*review-line-end\(\1\):\s*([\s\S]*?)\s*-->/g

Workflow

Step 1: Read and Parse

Read the file, extract all comments, present a summary:

Found 3 review comments in <filename>:

1. [inline] "implement caching" -> "Consider using Redis"
2. [line] "function fetchData()..." -> "Add error handling"
3. [inline] "TODO" -> "Please complete this"

Step 2: Process Each Comment

For each comment, show context and use AskUserQuestion:

• Apply edit: Propose changes, apply after confirmation, remove markers.
• Acknowledge: Remove markers, preserve content. Recommend this for praise/FYI.
• Skip: Leave as-is, move on.

Step 3: Remove Markers

• Inline: replace <!-- review-start(ID) -->text<!-- review-end(ID): feedback --> with text
• Line: replace the full block with just the content lines

Step 4: Final Summary

Processing complete!

- Applied edits: 2
- Acknowledged: 1
- Skipped: 0

File saved.

Special Cases

• FYI/Praise (“LGTM”, “Nice work”): Recommend Acknowledge as default
• Empty feedback: Ask if user wants to remove markers
• Unclear feedback: Use AskUserQuestion to clarify reviewer intent