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.
This commit is contained in:
Jesse Vincent
2026-06-10 03:44:19 -07:00
parent 29ee4e8e44
commit e355795625
2 changed files with 15 additions and 16 deletions

View File

@@ -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 - Include the spec/design's global constraints that bind the task (version
floors, naming and copy rules, platform requirements) in the requirements floors, naming and copy rules, platform requirements) in the requirements
you paste — a reviewer can only enforce what you hand them. you paste — a reviewer can only enforce what you hand them.
- Run `git diff BASE..HEAD` yourself and paste the output into the reviewer - Hand the reviewer its diff as a file: run
prompt (`--stat` plus the relevant hunks if it exceeds a few hundred `git diff BASE..HEAD > /tmp/sdd-task-N.diff` (redirected, so the diff
lines). A reviewer with the diff in hand needs few or no tool calls; do never enters your own context) and put that path in the prompt. The
not make reviewers re-derive the diff. 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 - Dispatch fix subagents for Critical and Important findings. Record Minor
findings and move on — then paste the accumulated Minor findings into the 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 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 - 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 dispatch prompt ("treat it as Minor at most") — the plan's example code is
a starting point, not evidence that its weaknesses were chosen a starting point, not evidence that its weaknesses were chosen
- Dispatch a task reviewer without pasting the diff into the prompt — run - Dispatch a task reviewer without a diff file — run
`git diff BASE..HEAD` yourself first (`--stat` plus relevant hunks if it `git diff BASE..HEAD > /tmp/sdd-task-N.diff` first and name that path in
exceeds a few hundred lines) the prompt
- Move to next task while the review has open Critical/Important issues - Move to next task while the review has open Critical/Important issues
**If subagent asks questions:** **If subagent asks questions:**

View File

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