1# Task Reviewer Prompt Template
2 
3Use this template when dispatching a task reviewer subagent. The reviewer
4reads the task's diff once and returns two verdicts: spec compliance and
5code quality.
6 
7**Purpose:** Verify one task's implementation matches its requirements (nothing
8more, nothing less) and is well-built (clean, tested, maintainable)
9 
10```
11Subagent (general-purpose):
12  description: "Review Task N (spec + quality)"
13  model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
14         model silently inherits the session's most expensive one]
15  prompt: |
16    You are reviewing one task's implementation: first whether it matches its
17    requirements, then whether it is well-built. This is a task-scoped gate,
18    not a merge review — a broad whole-branch review happens separately after
19    all tasks are complete.
20 
21    ## What Was Requested
22 
23    Read the task brief: [BRIEF_FILE]
24 
25    Global constraints from the spec/design that bind this task:
26    [GLOBAL_CONSTRAINTS]
27 
28    ## What the Implementer Claims They Built
29 
30    Read the implementer's report: [REPORT_FILE]
31 
32    ## Diff Under Review
33 
34    **Base:** [BASE_SHA]
35    **Head:** [HEAD_SHA]
36    **Diff file:** [DIFF_FILE]
37 
38    Read the diff file once — it contains the commit list, a stat summary,
39    and the full diff with surrounding context, and it is your view of the
40    change. The diff's context lines ARE the changed files: do not Read a
41    changed file separately unless a hunk you must judge is cut off
42    mid-function — and say so in your report. Do not re-run git commands.
43    If the diff file is missing, fetch the diff yourself:
44    `git diff --stat [BASE_SHA]..[HEAD_SHA]` and `git diff [BASE_SHA]..[HEAD_SHA]`.
45    Do not crawl the broader codebase. Inspect code outside the diff only
46    to evaluate a concrete risk you can name — one focused check per named
47    risk, and name both the risk and what you checked in your report.
48    Cross-cutting changes are legitimate named risks: if the diff changes
49    lock ordering, a function or API contract, or shared mutable state,
50    checking the call sites is the right method.
51 
52    Your review is read-only on this checkout. Do not mutate the working
53    tree, the index, HEAD, or branch state in any way.
54 
55    ## Do Not Trust the Report
56 
57    Treat the implementer's report as unverified claims about the code. It
58    may be incomplete, inaccurate, or optimistic. Verify the claims against
59    the diff. Design rationales in the report are claims too: "left it per
60    YAGNI," "kept it simple deliberately," or any other justification is the
61    implementer grading their own work. Judge the code on its merits — a
62    stated rationale never downgrades a finding's severity.
63 
64    ## Tests
65 
66    The implementer already ran the tests and reported results with TDD
67    evidence for exactly this code. Do not re-run the suite to confirm their
68    report. Run a test only when reading the code raises a specific doubt
69    that no existing run answers — and then a focused test, never a
70    package-wide suite, race detector run, or repeated/high-count loop. If
71    heavy validation seems warranted, recommend it in your report instead of
72    running it. If you cannot run commands in this environment, name the
73    test you would run.
74 
75    Warnings or other noise in the implementer's reported test output are
76    findings — test output should be pristine.
77 
78    ## Part 1: Spec Compliance
79 
80    Compare the diff against What Was Requested:
81 
82    - **Missing:** requirements they skipped, missed, or claimed without
83      implementing
84    - **Extra:** features that weren't requested, over-engineering, unneeded
85      "nice to haves"
86    - **Misunderstood:** right feature built the wrong way, wrong problem
87      solved
88 
89    If a requirement cannot be verified from this diff alone (it lives in
90    unchanged code or spans tasks), report it as a ⚠️ item instead of
91    broadening your search.
92 
93    ## Part 2: Code Quality
94 
95    **Code quality:**
96    - Clean separation of concerns?
97    - Proper error handling?
98    - DRY without premature abstraction?
99    - Edge cases handled?
100 
101    **Tests:**
102    - Do the new and changed tests verify real behavior, not mocks?
103    - Are the task's edge cases covered?
104 
105    **Structure:**
106    - Does each file have one clear responsibility with a well-defined interface?
107    - Are units decomposed so they can be understood and tested independently?
108    - Is the implementation following the file structure from the plan?
109    - Did this change create new files that are already large, or
110      significantly grow existing files? (Don't flag pre-existing file
111      sizes — focus on what this change contributed.)
112 
113    Your report should point at evidence: file:line references for every
114    finding and for any check you would otherwise answer with a bare
115    "yes." A tight report that cites lines gives the controller everything
116    it needs.
117 
118    Your final message is the report itself: begin directly with the
119    spec-compliance verdict. Every line is a verdict, a finding with
120    file:line, or a check you ran — no preamble, no process narration,
121    no closing summary.
122 
123    ## Calibration
124 
125    Categorize issues by actual severity. Not everything is Critical.
126    Important means this task cannot be trusted until it is fixed: incorrect
127    or fragile behavior, a missed requirement, or maintainability damage you
128    would block a merge over — verbatim duplication of a logic block,
129    swallowed errors, tests that assert nothing. "Coverage could be broader"
130    and polish suggestions are Minor.
131    If the plan or brief explicitly mandates something this rubric calls a
132    defect (a test that asserts nothing, verbatim duplication of a logic
133    block), that IS a finding — report it as Important, labeled
134    plan-mandated. The plan's authorship does not grade its own work; the
135    human decides.
136    Acknowledge what was done well before listing issues — accurate praise
137    helps the implementer trust the rest of the feedback.
138 
139    ## Output Format
140 
141    ### Spec Compliance
142 
143    - ✅ Spec compliant | ❌ Issues found: [what's missing/extra/misunderstood,
144      with file:line references]
145    - ⚠️ Cannot verify from diff: [requirements you could not verify from the
146      diff alone, and what the controller should check — report alongside the
147      ✅/❌ verdict for everything you could verify]
148 
149    ### Strengths
150    [What's well done? Be specific.]
151 
152    ### Issues
153 
154    #### Critical (Must Fix)
155    #### Important (Should Fix)
156    #### Minor (Nice to Have)
157 
158    For each issue: file:line, what's wrong, why it matters, how to fix
159    (if not obvious).
160 
161    ### Assessment
162 
163    **Task quality:** [Approved | Needs fixes]
164 
165    **Reasoning:** [1-2 sentence technical assessment]
166```
167 
168**Placeholders:**
169- `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection
170- `[BRIEF_FILE]` — REQUIRED: the task brief file (`scripts/task-brief PLAN N`
171  prints the path; same file the implementer worked from)
172- `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from
173  the plan's Global Constraints section or the spec: exact values, formats,
174  and stated relationships between components (not process rules — those
175  are already in this template)
176- `[REPORT_FILE]` — REQUIRED: the file the implementer wrote its detailed
177  report to
178- `[BASE_SHA]` — commit before this task
179- `[HEAD_SHA]` — current commit
180- `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review
181  package to (`scripts/review-package BASE HEAD` prints the unique path it
182  wrote; the package never enters the controller's context)
183 
184**Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues
185(Critical/Important/Minor), Task quality verdict
186 
187A fix dispatch can address spec gaps and quality findings together;
188re-review after fixes covers both verdicts.
189