From 1f8e0a3d2e09ea5a52cb4d250be4504d535f03fe Mon Sep 17 00:00:00 2001
From: mkorwel <matt.korwel@gmail.com>
Date: Fri, 13 Mar 2026 17:49:35 -0700
Subject: [PATCH] docs: add documentation for deep-review maintainer skill

---
 docs/cli/deep-review.md | 108 ++++++++++++++++++++++++++++++++++++++++
 docs/sidebar.json       |   3 +-
 2 files changed, 110 insertions(+), 1 deletion(-)
 create mode 100644 docs/cli/deep-review.md

diff --git a/docs/cli/deep-review.md b/docs/cli/deep-review.md
new file mode 100644
index 0000000000..fab779e89d
--- /dev/null
+++ b/docs/cli/deep-review.md
@@ -0,0 +1,108 @@
+# Deep review maintainer skill
+
+The deep review skill provides a high-performance, parallelized workflow for
+reviewing pull requests on a remote workstation. It leverages a Node.js
+orchestrator to offload intensive builds and automated testing to parallel
+background processes, showing progress in a dedicated terminal window.
+
+This workflow follows a "Verify then Synthesize" pattern, allowing you to
+monitor infrastructure validation and behavioral proofs in real-time before
+conducting the final interactive review with Gemini CLI.
+
+## Scenarios and workflows
+
+The following scenarios outline how to use the deep review skill effectively.
+
+### First-time setup
+
+Before running your first deep review, you must configure your remote
+workstation.
+
+1.  Run the setup command:
+    ```bash
+    npm run review:setup
+    ```
+2.  Follow the interactive prompts to specify:
+    - **Remote SSH Host**: The alias for your remote machine (default: `cli`).
+    - **Remote Work Directory**: Where PR worktrees will be provisioned.
+    - **Identity Synchronization**: Whether to mirror your local `.gemini`
+      credentials to the remote host.
+    - **Terminal Automation**: Your preferred terminal emulator (for example,
+      `iterm2` or `terminal`).
+
+The setup script automatically installs `tsx` and the nightly version of Gemini
+CLI on the remote host in an isolated directory.
+
+### Launching a review
+
+To start a deep review for a specific pull request, use the `review` script.
+
+1.  Execute the review command with the PR number:
+    ```bash
+    npm run review <PR_NUMBER>
+    ```
+2.  The orchestrator performs the following actions:
+    - Fetches PR metadata and branch information.
+    - Synchronizes the latest review scripts to your remote host.
+    - Mirrors your local environment and credentials (if configured).
+    - Opens a new terminal window and connects to a remote `tmux` session.
+
+### Remote parallel execution
+
+Once the remote session starts, the worker process automatically provisions a
+blobless git clone for the PR and launches four tasks in parallel:
+
+- **Fast Build**: Executes `npm ci && npm run build` to prepare the environment.
+- **CI Checks**: Monitors the status of GitHub Actions for the PR.
+- **Gemini Analysis**: Performs a static analysis using the `/review-frontend`
+  command.
+- **Behavioral Proof**: Exercises the new code in the terminal to verify
+  functionality. This task waits for the **Fast Build** to complete.
+
+You can monitor the live status and logs for all these tasks in the dedicated
+terminal window.
+
+### Monitoring and synthesis
+
+While verification is running, your main Gemini CLI session remains interactive.
+
+1.  To check progress from your local shell without switching windows:
+    ```bash
+    npm run review:check <PR_NUMBER>
+    ```
+2.  Once all tasks show as **SUCCESS**, the remote session automatically
+    launches an interactive Gemini session.
+3.  Gemini CLI reads the captured logs from `.gemini/logs/review-<PR_NUMBER>/`
+    and presents a synthesized final assessment.
+
+### Cleanup
+
+To keep your remote workstation tidy, you can wipe old PR directories and kill
+inactive sessions.
+
+1.  Run the cleanup command:
+    ```bash
+    npm run review:clean
+    ```
+2.  You can choose to perform a standard cleanup (remove worktrees) or a full
+    wipe of the remote work directory.
+
+## Best practices
+
+Adhere to these best practices when using the deep review skill.
+
+- **Trust the worker**: Avoid running manual builds or linting in your main
+  session. The parallel worker is more efficient and captures structured logs
+  for the agent to read later.
+- **Verify behavior**: Pay close attention to the `test-execution.log`. It
+  provides the physical proof that the feature actually works in a live
+  environment.
+- **Use isolated profiles**: The skill uses `~/.gemini-deep-review` on the
+  remote host to avoid interfering with your primary Gemini CLI configuration.
+
+## Next steps
+
+- [Skills](skills.md): Learn more about how Gemini CLI uses skills to expand
+  capabilities.
+- [Session management](session-management.md): Understand how to manage your
+  local and remote Gemini sessions.
diff --git a/docs/sidebar.json b/docs/sidebar.json
index 6cac5ec9fd..f683188138 100644
--- a/docs/sidebar.json
+++ b/docs/sidebar.json
@@ -178,7 +178,8 @@
             "slug": "docs/issue-and-pr-automation"
           },
           { "label": "Local development", "slug": "docs/local-development" },
-          { "label": "NPM package structure", "slug": "docs/npm" }
+          { "label": "NPM package structure", "slug": "docs/npm" },
+          { "label": "Deep PR review", "slug": "docs/cli/deep-review" }
         ]
       }
     ]