Requesting Code Review
Dispatch a reviewer subagent using the canonical code-reviewer.md template to
catch issues before they cascade. The reviewer gets precisely crafted context
for evaluation — never your session's history. This keeps the reviewer focused
on the work product, not your thought process, and preserves your own context
for continued work.
This skill is the canonical review-request workflow for method-pack implementation work. Use it to request review only after you have enough evidence, enough context, and a clear authority boundary for what the reviewer is being asked to assess.
Core principle: Review early, review often.
Findings First: Reviews lead with concrete findings before summary. Use
bugs first, risk first, tests first. Strengths and general assessment are still
useful, but they must not bury correctness, evidence, architecture, or
retirement problems.
Review readiness is not merge approval. A review can reduce uncertainty and
recommend readiness, but it does not replace verification-before-completion
and does not grant completion authority.
When to Request Review
Mandatory:
- After each task in subagent-driven development
- After completing major feature
- Before merge to main
Optional but valuable:
- When stuck (fresh perspective)
- Before refactoring (baseline check)
- After fixing complex bug
Required Outputs
Before you leave this workflow, you must be able to state:
- What exact scope is being reviewed
- What plan, requirement, or contract defines success
- What Product / Requirement Baseline defines accepted behavior and non-goals
- What Architecture / Runtime Boundary Baseline defines the expected architecture state
- What fresh evidence already exists
- What compatibility boundary must still hold
- What old owner / fallback / patch stays, shrinks, or retires
- What the reviewer must specifically validate
- Whether the reviewer is providing advisory review only, or also any higher-level merge recommendation
- Aegis Visibility: why findings-first ordering, evidence sufficiency,
baseline alignment, compatibility, or retirement risk matters for this
review request
- Semantic context scope: which relevant canonical terms, deprecated
aliases, or public naming boundaries the review must preserve
Review in this method pack is advisory and evidence-oriented. It is not authoritative completion by itself.
How to Request
1. Gather minimum review inputs:
- What was implemented
- What requirement / plan / spec / ADR it should match
- What baseline / current authority docs the diff must align with, including
requirements/product alignment and architecture/current-authority alignment
- What evidence already exists (tests, commands, logs, screenshots, diff summary)
- What compatibility boundary or risk deserves reviewer attention
- Whether there is any old path, fallback, duplicate owner, or temporary patch that should retire
- Whether the diff contains durable architecture decisions that need ADR
Auto Backfill or baseline sync findings
- Whether
recording-architecture-decisions was used, or should be used, when
an ADR action or baseline sync closure is in scope
- Relevant active
CONTEXT.md language when public/domain naming is in scope;
passive reading does not load active modeling
If you cannot answer these, stop and gather them before dispatching review.
2. Define the Git review scope:
# Before the coordinator's task commit
REVIEW_SCOPE=working-tree
BASE_SHA=$(git rev-parse HEAD)
# Or for already committed work
REVIEW_SCOPE=committed-range
BASE_SHA=<known-start>
HEAD_SHA=$(git rev-parse HEAD)
For working-tree review, identify task-owned untracked paths explicitly. Do not
stage merely to make them visible to a reviewer.
3. Dispatch reviewer subagent:
Use the Task tool with a general-purpose reviewer subagent. Fill the canonical
template at requesting-code-review/code-reviewer.md; do not rely on a
separate named agent prompt.
Placeholders:
{WHAT_WAS_IMPLEMENTED} - What you just built
{PLAN_OR_REQUIREMENTS} - What it should do
{EVIDENCE} - Fresh tests, commands, logs, or verification already available
{COMPATIBILITY_BOUNDARY} - What existing behavior or interfaces must not break
{RETIREMENT_NOTES} - Old owner / fallback / patch / duplicate branch and expected disposition
{REVIEW_SCOPE} - working-tree or committed-range
{BASE_SHA} - Starting commit
{HEAD_SHA} - Ending commit, or WORKTREE
{DESCRIPTION} - Brief summary
4. Act on feedback:
- Fix Critical issues immediately
- Fix Important issues before proceeding
- Note Minor issues for later
- Push back if reviewer is wrong (with reasoning)
- If feedback reveals evidence gaps, run the missing verification instead of arguing from confidence
- If feedback reveals Design Defect / Implementation Drift, stale logic, or a
legacy alias such as architecture drift, decide explicitly whether to repair
now, correct the baseline, or record retirement conditions
Example
[Just completed Task 2: Add verification function]
You: Let me request code review before proceeding.
BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
HEAD_SHA=$(git rev-parse HEAD)
[Dispatch reviewer subagent using requesting-code-review/code-reviewer.md]
WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
PLAN_OR_REQUIREMENTS: Task 2 from docs/aegis/plans/deployment-plan.md
EVIDENCE: pytest tests/index/test_verify.py -v -> 12 passed
COMPATIBILITY_BOUNDARY: Existing index format and CLI flags must remain stable
RETIREMENT_NOTES: Legacy repair fallback still exists in old helper; remove once new path covers all four issue types
BASE_SHA: a7981ec
HEAD_SHA: 3df7661
DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
[Subagent returns]:
Strengths: Clean architecture, real tests
Issues:
Important: Missing progress indicators
Minor: Magic number (100) for reporting interval
Assessment: Ready to proceed
You: [Fix progress indicators]
[Continue to Task 3]
Integration with Workflows
Subagent-Driven Development:
- Review after EACH task
- Catch issues before they compound
- Fix before moving to next task
Executing Plans:
- Review after each batch (3 tasks)
- Get feedback, apply, continue
Ad-Hoc Development:
- Review before merge
- Review when stuck
What the Reviewer Must Check
The review request must prompt the reviewer to inspect at least:
- Findings First: bugs first, risk first, tests first
- evidence sufficiency
- baseline / current authority alignment
- requirements/product alignment against accepted problem, success evidence, and
non-goals
- architecture/current-authority alignment against owner, contract,
source-of-truth, compatibility, and retirement boundaries
- Design Defect / Implementation Drift classification with
scope: requirements | architecture | both
- legacy phrase mapping: baseline defect, architecture defect, and architecture
drift must map back to Design Defect / Implementation Drift rather than
becoming parallel result vocabularies
- duplicate owner risk
- compatibility boundary
- missing ADR Auto Backfill or baseline sync findings for durable architecture
decisions
- missing
recording-architecture-decisions handoff when ADR action or
baseline sync closure is in scope
- unverified claims or missing proof
- old logic that should retire, stay temporarily, or converge
- public-name drift, deprecated-term re-entry, or a semantic change recorded in
code/docs without composing
establishing-project-context
If the review only asks “is this code good?”, it is underspecified.
Red Flags
Never:
- Skip review because "it's simple"
- Ignore Critical issues
- Proceed with unfixed Important issues
- Argue with valid technical feedback
- Treat reviewer approval as equivalent to authoritative completion
- Ask for review without sharing what evidence already exists
- Add new logic without telling the reviewer what happens to the old path
If reviewer wrong:
- Push back with technical reasoning
- Show code/tests that prove it works
- Request clarification
Review Boundaries
- Review can recommend merge readiness, residual risk, and follow-up work
- Review cannot grant authoritative completion by itself
- Review should reduce uncertainty, not hide it
See template at: requesting-code-review/code-reviewer.md
1---
2name: requesting-code-review
3description: "Use when requesting independent code review, after implementation slices, before merging high-risk work, or when verification exposes evidence, baseline, architecture, compatibility, or retirement uncertainty."
4metadata:
5 source: https://skillmd.com/skills/ganyuanran/requesting-code-review
6---
7
8# Requesting Code Review
9
10Dispatch a reviewer subagent using the canonical `code-reviewer.md` template to
11catch issues before they cascade. The reviewer gets precisely crafted context
12for evaluation — never your session's history. This keeps the reviewer focused
13on the work product, not your thought process, and preserves your own context
14for continued work.
15
16This skill is the canonical review-request workflow for method-pack implementation work. Use it to request review only after you have enough evidence, enough context, and a clear authority boundary for what the reviewer is being asked to assess.
17
18**Core principle:** Review early, review often.
19
20**Findings First:** Reviews lead with concrete findings before summary. Use
21bugs first, risk first, tests first. Strengths and general assessment are still
22useful, but they must not bury correctness, evidence, architecture, or
23retirement problems.
24
25Review readiness is not merge approval. A review can reduce uncertainty and
26recommend readiness, but it does not replace `verification-before-completion`
27and does not grant completion authority.
28
29## When to Request Review
30
31**Mandatory:**
32- After each task in subagent-driven development
33- After completing major feature
34- Before merge to main
35
36**Optional but valuable:**
37- When stuck (fresh perspective)
38- Before refactoring (baseline check)
39- After fixing complex bug
40
41## Required Outputs
42
43Before you leave this workflow, you must be able to state:
44
451. **What exact scope is being reviewed**
462. **What plan, requirement, or contract defines success**
473. **What Product / Requirement Baseline defines accepted behavior and non-goals**
484. **What Architecture / Runtime Boundary Baseline defines the expected architecture state**
495. **What fresh evidence already exists**
506. **What compatibility boundary must still hold**
517. **What old owner / fallback / patch stays, shrinks, or retires**
528. **What the reviewer must specifically validate**
539. **Whether the reviewer is providing advisory review only, or also any higher-level merge recommendation**
5410. **Aegis Visibility**: why findings-first ordering, evidence sufficiency,
55 baseline alignment, compatibility, or retirement risk matters for this
56 review request
5711. **Semantic context scope**: which relevant canonical terms, deprecated
58 aliases, or public naming boundaries the review must preserve
59
60Review in this method pack is advisory and evidence-oriented. It is not authoritative completion by itself.
61
62## How to Request
63
64**1. Gather minimum review inputs:**
65
66- What was implemented
67- What requirement / plan / spec / ADR it should match
68- What baseline / current authority docs the diff must align with, including
69 requirements/product alignment and architecture/current-authority alignment
70- What evidence already exists (tests, commands, logs, screenshots, diff summary)
71- What compatibility boundary or risk deserves reviewer attention
72- Whether there is any old path, fallback, duplicate owner, or temporary patch that should retire
73- Whether the diff contains durable architecture decisions that need ADR
74 Auto Backfill or baseline sync findings
75- Whether `recording-architecture-decisions` was used, or should be used, when
76 an ADR action or baseline sync closure is in scope
77- Relevant active `CONTEXT.md` language when public/domain naming is in scope;
78 passive reading does not load active modeling
79
80If you cannot answer these, stop and gather them before dispatching review.
81
82**2. Define the Git review scope:**
83```bash
84# Before the coordinator's task commit
85REVIEW_SCOPE=working-tree
86BASE_SHA=$(git rev-parse HEAD)
87
88# Or for already committed work
89REVIEW_SCOPE=committed-range
90BASE_SHA=<known-start>
91HEAD_SHA=$(git rev-parse HEAD)
92```
93
94For working-tree review, identify task-owned untracked paths explicitly. Do not
95stage merely to make them visible to a reviewer.
96
97**3. Dispatch reviewer subagent:**
98
99Use the Task tool with a general-purpose reviewer subagent. Fill the canonical
100template at `requesting-code-review/code-reviewer.md`; do not rely on a
101separate named agent prompt.
102
103**Placeholders:**
104- `{WHAT_WAS_IMPLEMENTED}` - What you just built
105- `{PLAN_OR_REQUIREMENTS}` - What it should do
106- `{EVIDENCE}` - Fresh tests, commands, logs, or verification already available
107- `{COMPATIBILITY_BOUNDARY}` - What existing behavior or interfaces must not break
108- `{RETIREMENT_NOTES}` - Old owner / fallback / patch / duplicate branch and expected disposition
109- `{REVIEW_SCOPE}` - `working-tree` or `committed-range`
110- `{BASE_SHA}` - Starting commit
111- `{HEAD_SHA}` - Ending commit, or `WORKTREE`
112- `{DESCRIPTION}` - Brief summary
113
114**4. Act on feedback:**
115- Fix Critical issues immediately
116- Fix Important issues before proceeding
117- Note Minor issues for later
118- Push back if reviewer is wrong (with reasoning)
119- If feedback reveals evidence gaps, run the missing verification instead of arguing from confidence
120- If feedback reveals Design Defect / Implementation Drift, stale logic, or a
121 legacy alias such as architecture drift, decide explicitly whether to repair
122 now, correct the baseline, or record retirement conditions
123
124## Example
125
126```
127[Just completed Task 2: Add verification function]
128
129You: Let me request code review before proceeding.
130
131BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
132HEAD_SHA=$(git rev-parse HEAD)
133
134[Dispatch reviewer subagent using requesting-code-review/code-reviewer.md]
135 WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
136 PLAN_OR_REQUIREMENTS: Task 2 from docs/aegis/plans/deployment-plan.md
137 EVIDENCE: pytest tests/index/test_verify.py -v -> 12 passed
138 COMPATIBILITY_BOUNDARY: Existing index format and CLI flags must remain stable
139 RETIREMENT_NOTES: Legacy repair fallback still exists in old helper; remove once new path covers all four issue types
140 BASE_SHA: a7981ec
141 HEAD_SHA: 3df7661
142 DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
143
144[Subagent returns]:
145 Strengths: Clean architecture, real tests
146 Issues:
147 Important: Missing progress indicators
148 Minor: Magic number (100) for reporting interval
149 Assessment: Ready to proceed
150
151You: [Fix progress indicators]
152[Continue to Task 3]
153```
154
155## Integration with Workflows
156
157**Subagent-Driven Development:**
158- Review after EACH task
159- Catch issues before they compound
160- Fix before moving to next task
161
162**Executing Plans:**
163- Review after each batch (3 tasks)
164- Get feedback, apply, continue
165
166**Ad-Hoc Development:**
167- Review before merge
168- Review when stuck
169
170## What the Reviewer Must Check
171
172The review request must prompt the reviewer to inspect at least:
173
174- Findings First: bugs first, risk first, tests first
175- evidence sufficiency
176- baseline / current authority alignment
177- requirements/product alignment against accepted problem, success evidence, and
178 non-goals
179- architecture/current-authority alignment against owner, contract,
180 source-of-truth, compatibility, and retirement boundaries
181- Design Defect / Implementation Drift classification with
182 `scope: requirements | architecture | both`
183- legacy phrase mapping: baseline defect, architecture defect, and architecture
184 drift must map back to Design Defect / Implementation Drift rather than
185 becoming parallel result vocabularies
186- duplicate owner risk
187- compatibility boundary
188- missing ADR Auto Backfill or baseline sync findings for durable architecture
189 decisions
190- missing `recording-architecture-decisions` handoff when ADR action or
191 baseline sync closure is in scope
192- unverified claims or missing proof
193- old logic that should retire, stay temporarily, or converge
194- public-name drift, deprecated-term re-entry, or a semantic change recorded in
195 code/docs without composing `establishing-project-context`
196
197If the review only asks “is this code good?”, it is underspecified.
198
199## Red Flags
200
201**Never:**
202- Skip review because "it's simple"
203- Ignore Critical issues
204- Proceed with unfixed Important issues
205- Argue with valid technical feedback
206- Treat reviewer approval as equivalent to authoritative completion
207- Ask for review without sharing what evidence already exists
208- Add new logic without telling the reviewer what happens to the old path
209
210**If reviewer wrong:**
211- Push back with technical reasoning
212- Show code/tests that prove it works
213- Request clarification
214
215## Review Boundaries
216
217- Review can recommend merge readiness, residual risk, and follow-up work
218- Review cannot grant authoritative completion by itself
219- Review should reduce uncertainty, not hide it
220
221See template at: requesting-code-review/code-reviewer.md