---
name: requesting-code-review
description: >-
  Use when completing a plan, finishing a feature, or before phase verification.
  Dispatches gmd-verifier stage-2 with structured git diff context so review
  focuses on the work product, not thought process.
type: behavioral
trigger-patterns:
  - completing a plan
  - finishing a feature
  - before phase verification
  - before merging to main
discipline: rigid
allowed-tools:
  - Bash
  - Task
  - Read
category: verification
tags:
  - review
  - quality
  - verification
agents:
  - gmd-executor
  - gmd-planner
---

# Requesting Review

## Overview

Dispatch `gmd-verifier` stage-2 (code-quality) to catch issues before they cascade. The verifier 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.

**Core principle:** Review early, review often. Fresh context only.

## The Iron Law

```
NEVER CLAIM A PLAN IS COMPLETE WITHOUT A STAGE-2 CODE-QUALITY REVIEW
```

If you have not dispatched `gmd-verifier` with `stage_2: code_quality` against the diff since your last substantive change, you cannot mark work done, commit a final artifact, or advance to the next plan.

**Violating the letter of this rule is violating the spirit of this rule.**

## When to Request Review

**Mandatory:**

- After each task in subagent-driven development
- After completing a plan or major feature
- Before phase verification
- Before merge to main

**Optional but valuable:**

- When stuck (fresh perspective)
- Before refactoring (baseline check)
- After fixing a complex bug

## How to Request

### Step 1: Get git SHAs

```bash
BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main, or start-of-plan commit
HEAD_SHA=$(git rev-parse HEAD)
```

Choose `BASE_SHA` to cover the full change surface for the work you are claiming complete. For a plan, that is usually the commit before Task 1.

### Step 2: Dispatch gmd-verifier stage-2

Use the `Task` tool with `subagent_type="gmd-verifier"` and an explicit `<stages>` block selecting `stage_2: code_quality`. Do NOT spawn any other agent type for code review — GMD uses `gmd-verifier` for both stage-1 (goal-backward) and stage-2 (quality), gated by the stages block.

### GMD Dispatch Shape

```
Task(
  subagent_type="gmd-verifier",
  model="{resolved-model}",
  description="Stage-2 code-quality review",
  prompt="""
    <stages>
    stage_2: code_quality
    </stages>

    <diff_range>
    base: {BASE_SHA}
    head: {HEAD_SHA}
    </diff_range>

    <what_was_implemented>
    {WHAT_WAS_IMPLEMENTED}
    </what_was_implemented>

    <plan_or_requirements>
    {PLAN_OR_REQUIREMENTS}
    </plan_or_requirements>

    <description>
    {DESCRIPTION}
    </description>

    <review_checklist>
    {REVIEW_CHECKLIST}
    </review_checklist>
  """
)
```

**Placeholders:**

- `{WHAT_WAS_IMPLEMENTED}` — What you just built (concrete artifacts, not intent)
- `{PLAN_OR_REQUIREMENTS}` — The plan, requirement IDs, or spec the work must satisfy
- `{BASE_SHA}` — Starting commit for the diff
- `{HEAD_SHA}` — Ending commit for the diff
- `{DESCRIPTION}` — Brief summary (1–3 sentences)
- `{REVIEW_CHECKLIST}` — The structured checklist below

### Step 3: Act on feedback

- Fix Critical issues immediately
- Fix Important issues before proceeding
- Note Minor issues for later
- Push back if the verifier is wrong (with technical reasoning and evidence)

## Structured Review Checklist

Pass this checklist to `gmd-verifier` inside the `<review_checklist>` block so stage-2 output is uniform across reviews.

```
You are reviewing code changes for production readiness.

## Your Task
1. Review {WHAT_WAS_IMPLEMENTED}
2. Compare against {PLAN_OR_REQUIREMENTS}
3. Check code quality, architecture, testing
4. Categorize issues by severity
5. Assess production readiness

## Git Range to Review
Base: {BASE_SHA}
Head: {HEAD_SHA}

Run:
  git diff --stat {BASE_SHA}..{HEAD_SHA}
  git diff {BASE_SHA}..{HEAD_SHA}

## Review Checklist

### Code Quality
- Clean separation of concerns?
- Proper error handling?
- Type safety (if applicable)?
- DRY principle followed?
- Edge cases handled?

### Architecture
- Sound design decisions?
- Scalability considerations?
- Performance implications?
- Security concerns?

### Testing
- Tests exercise real logic (not mocks)?
- Edge cases covered?
- Integration tests where needed?
- All tests passing?

### Requirements
- All plan requirements met?
- Implementation matches spec?
- No scope creep?
- Breaking changes documented?

### Production Readiness
- Migration strategy (if schema changes)?
- Backward compatibility considered?
- Documentation complete?
- No obvious bugs?

## Output Format

### Strengths
[What is well done? Be specific with file:line references.]

### Issues

#### Critical (Must Fix)
[Bugs, security issues, data loss risks, broken functionality]

#### Important (Should Fix)
[Architecture problems, missing features, poor error handling, test gaps]

#### Minor (Nice to Have)
[Style, optimization opportunities, documentation improvements]

For each issue:
- file:line reference
- What is wrong
- Why it matters
- How to fix (if not obvious)

### Recommendations
[Improvements for code quality, architecture, or process]

### Assessment
Ready to merge? [Yes / No / With fixes]
Reasoning: [1–2 sentence technical assessment]

## Critical Rules

DO:
- Categorize by actual severity (not everything is Critical)
- Be specific (file:line, not vague)
- Explain WHY issues matter
- Acknowledge strengths
- Give a clear verdict

DON'T:
- Say "looks good" without checking
- Mark nitpicks as Critical
- Give feedback on files you did not read
- Be vague ("improve error handling")
- Avoid giving a clear verdict
```

## Example

```
[Just completed Task 2: Add verification function]

You: Dispatching gmd-verifier stage-2 before claiming done.

BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
HEAD_SHA=$(git rev-parse HEAD)

[Task subagent_type=gmd-verifier, stages=stage_2: code_quality, base=a7981ec, head=3df7661]

[Stage-2 returns]
  Strengths: Clean architecture, real tests
  Issues:
    Important: Missing progress indicators
    Minor: Magic number (100) for reporting interval
  Assessment: Ready to proceed, with fixes

You: [Fix progress indicators, re-run verification, THEN claim task done]
```

## Integration with Workflows

**Subagent-driven development:**

- Review after each task
- Catch issues before they compound
- Fix before moving to the next task

**Executing plans:**

- Review after each batch (3 tasks) or at plan boundary
- Get feedback, apply, continue

**Ad-hoc development:**

- Review before merge
- Review when stuck

## Red Flags — STOP

- Skipping review because "it is simple"
- Ignoring Critical issues
- Proceeding with unfixed Important issues
- Arguing with valid technical feedback
- Dispatching anything other than `gmd-verifier` for stage-2
- Claiming the plan is complete before the stage-2 report arrives
- "I'll request review after the commit" (commit protocol includes review — there is no after)

## When the Verifier Is Wrong

- Push back with technical reasoning, not defensiveness
- Show code or tests that prove it works
- Request clarification on ambiguous findings
- Involve the user if the disagreement is architectural

## Domain Rationalization Prevention

These domain-specific patterns extend the universal `rationalization-prevention` skill:

| Thought                                        | Reality                                                                                         |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| "It's just a small change, no review needed"   | Small changes cause cascade failures. Dispatch `gmd-verifier` stage-2 anyway.                   |
| "I'll review it myself in the next message"    | Self-review in the same context has zero signal. Fresh context only.                            |
| "Stage 1 already ran, stage 2 is redundant"    | Stage 1 is goal-backward. Stage 2 is code-quality. Distinct dimensions — see `gmd-verifier.md`. |
| "The user said just commit it"                 | Requesting review IS the commit protocol. No exceptions.                                        |
| "The diff is too small to be worth a dispatch" | Small diffs are cheap to review. Cost is not the gate; discipline is.                           |
| "I already ran tests locally"                  | Tests answer "does it run?" Review answers "should it run that way?" Different dimensions.      |
| "The planner already approved the approach"   | Approved approach does not equal approved implementation. Review the code.                      |

## The Bottom Line

Stage-2 review is not optional finishing polish. It is the gate between "I wrote code" and "this plan is complete." Dispatch `gmd-verifier` with `stage_2: code_quality`, read the report, act on it. Only then claim done.
