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