From b2212dc9135efff326167bdff0323ee4a3dcb5a5 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@primeradiant.com>
Date: Sat, 23 May 2026 16:14:05 -0700
Subject: [PATCH] Scope spec reviewer to task diff and make reviewers read-only

Two problems with the SDD reviewer prompts on dev:

- spec-reviewer-prompt.md never received a git range, so the
  general-purpose subagent had to crawl the entire codebase to find what
  changed. Reporter measured 20-33 minute spec reviews on simple tasks
  (#1538).
- Neither reviewer prompt told the subagent that review is read-only.
  A spec reviewer running `git checkout <parent-sha>` for historical
  comparison silently detached HEAD on the controller's branch, then
  subsequent task commits accumulated on the detached HEAD and were
  effectively orphaned (#1543, reproduced independently in #1543's
  thread).

Add a Git Range to Review section to spec-reviewer-prompt.md that
mirrors the one code-reviewer.md already has, plus a Read-Only Review
section in both reviewer prompt templates stating the principle: do
not mutate the working tree, the index, HEAD, or branch state. Allow
inspecting other revisions via a separate temporary worktree, so the
read-only rule does not block legitimate historical comparison.

Closes #1538.
Closes #1543.
---
 skills/requesting-code-review/code-reviewer.md   |  4 ++++
 .../spec-reviewer-prompt.md                      | 16 ++++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/skills/requesting-code-review/code-reviewer.md b/skills/requesting-code-review/code-reviewer.md
index eb3ad887..e6089c9e 100644
--- a/skills/requesting-code-review/code-reviewer.md
+++ b/skills/requesting-code-review/code-reviewer.md
@@ -30,6 +30,10 @@ Subagent (general-purpose):
     git diff {BASE_SHA}..{HEAD_SHA}
     ```
 
+    ## Read-Only Review
+
+    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-{SHA} {SHA}`) — never move HEAD on this checkout.
+
     ## What to Check
 
     **Plan alignment:**
diff --git a/skills/subagent-driven-development/spec-reviewer-prompt.md b/skills/subagent-driven-development/spec-reviewer-prompt.md
index 4ac2d7b4..1cc84a76 100644
--- a/skills/subagent-driven-development/spec-reviewer-prompt.md
+++ b/skills/subagent-driven-development/spec-reviewer-prompt.md
@@ -18,6 +18,22 @@ Subagent (general-purpose):
 
     [From implementer's report]
 
+    ## Git Range to Review
+
+    **Base:** [BASE_SHA — commit before this task]
+    **Head:** [HEAD_SHA — current commit]
+
+    ```bash
+    git diff --stat [BASE_SHA]..[HEAD_SHA]
+    git diff [BASE_SHA]..[HEAD_SHA]
+    ```
+
+    Only read files in this diff. Do not crawl the broader codebase.
+
+    ## Read-Only Review
+
+    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
+
     ## CRITICAL: Do Not Trust the Report
 
     The implementer finished suspiciously quickly. Their report may be incomplete,