requesting-code-review

Files (2)

• SKILL.md
• code-reviewer.md

SKILL.md (first lines)

# 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:

1. **What exact scope is being reviewed**
2. **What plan, requirement, or contract defines success**
3. **What Product / Requirement Baseline defines accepted behavior and non-goals**
4. **What Architecture / Runtime Boundary Baseline defines the expected architecture state**
5. **What fresh evidence already exists**
6. **What compatibility boundary must still hold**
7. **What old owner / fallback / patch stays, shrinks, or retires**
8. **What the reviewer must specifically validate**
9. **Whether the reviewer is providing advisory review only, or also any higher-level merge recommendation**
10. **Aegis Visibility**: why findings-first ordering, evidence sufficiency,
    baseline alignment, compatibility, or retirement risk matters for this
    review request
11. **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.

Compare requirements and result in both directions: omissions or weakening,
and unsupported additions or strengthening. Preserve relevant relationships,
behavior, ownership and qualifiers within the authorized transformation. Pair
an evidenced defect with a relevant valid case; do not add acceptance criteria,
reject authorized summaries or corrections, or require exhaustive equivalence.

## 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:**
```bash
# 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

From GanyuanRan/Aegis, MIT.

More from GanyuanRan/Aegis