Browse Source

Hand reviewers the diff as a file, not a paste

Paste adoption stayed at 0/15 even as a Red Flag — and the controller's
reluctance is locally rational: pasting loads the diff into the (most
expensive) controller context permanently, while a reviewer self-fetch
costs a few cheap turns. The diff-file handoff is cheap for both sides:
the controller redirects git diff to /tmp without reading it, and the
reviewer gets the whole change in one Read call.
Jesse Vincent 3 months ago
parent
commit
a0dcb77596

+ 8 - 7
skills/subagent-driven-development/SKILL.md

@@ -153,10 +153,11 @@ final whole-branch review. When you fill a reviewer template:
 - Include the spec/design's global constraints that bind the task (version
   floors, naming and copy rules, platform requirements) in the requirements
   you paste — a reviewer can only enforce what you hand them.
-- Run `git diff BASE..HEAD` yourself and paste the output into the reviewer
-  prompt (`--stat` plus the relevant hunks if it exceeds a few hundred
-  lines). A reviewer with the diff in hand needs few or no tool calls; do
-  not make reviewers re-derive the diff.
+- Hand the reviewer its diff as a file: run
+  `git diff BASE..HEAD > /tmp/sdd-task-N.diff` (redirected, so the diff
+  never enters your own context) and put that path in the prompt. The
+  reviewer then sees the whole change in one Read call instead of
+  re-deriving it with git commands.
 - Dispatch fix subagents for Critical and Important findings. Record Minor
   findings and move on — then paste the accumulated Minor findings into the
   final whole-branch review dispatch so it can triage which must be fixed
@@ -282,9 +283,9 @@ Done!
 - Tell a reviewer what not to flag, or pre-rate a finding's severity in the
   dispatch prompt ("treat it as Minor at most") — the plan's example code is
   a starting point, not evidence that its weaknesses were chosen
-- Dispatch a task reviewer without pasting the diff into the prompt — run
-  `git diff BASE..HEAD` yourself first (`--stat` plus relevant hunks if it
-  exceeds a few hundred lines)
+- Dispatch a task reviewer without a diff file — run
+  `git diff BASE..HEAD > /tmp/sdd-task-N.diff` first and name that path in
+  the prompt
 - Move to next task while the review has open Critical/Important issues
 
 **If subagent asks questions:**

+ 7 - 9
skills/subagent-driven-development/task-reviewer-prompt.md

@@ -27,13 +27,11 @@ Subagent (general-purpose):
 
     **Base:** [BASE_SHA]
     **Head:** [HEAD_SHA]
+    **Diff file:** [DIFF_FILE]
 
-    [DIFF — REQUIRED: the controller pastes `git diff BASE..HEAD` output
-    here before dispatching. Dispatching with this placeholder unfilled is
-    a dispatch error.]
-
-    Review from the diff above — do not re-run git commands or re-read the
-    files it already shows. If no diff was provided, fetch it yourself:
+    Read the diff file once — that single Read is your view of the change.
+    Do not re-run git commands or re-read the files it already shows. If
+    the diff file is missing, fetch the diff yourself:
     `git diff --stat [BASE_SHA]..[HEAD_SHA]` and `git diff [BASE_SHA]..[HEAD_SHA]`.
     Only read files in this diff. Do not crawl the broader codebase. Inspect
     code outside the diff only to evaluate a concrete risk you can name — and
@@ -153,9 +151,9 @@ Subagent (general-purpose):
 - `[DESCRIPTION]` — what the implementer reports they built
 - `[BASE_SHA]` — commit before this task
 - `[HEAD_SHA]` — current commit
-- `[DIFF]` — REQUIRED: paste `git diff BASE..HEAD` output (use `--stat`
-  plus the relevant hunks if it exceeds a few hundred lines); a reviewer
-  with the diff in hand needs few or no tool calls
+- `[DIFF_FILE]` — REQUIRED: the path the controller wrote the diff to
+  (`git diff BASE..HEAD > /tmp/sdd-task-N.diff`, redirected so it never
+  enters the controller's context)
 
 **Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues
 (Critical/Important/Minor), Task quality verdict