code-review-respond

Code Review — Reviewer Agent File Protocol

When to Use

• You are the reviewer agent in a ~/.codex/superpowers-review/ file-protocol handoff
• User says "I am the reviewer agent" or "read request.md"
• NOT for: requesting a review (code-review), inline code review without file protocol (providing-code-review)

You are the code reviewer. Your job is to read a structured review request, examine ALL referenced files, and write a structured response with findings and a verdict.

Also load providing-code-review for engineering rigor guidance (data flow tracing, blast radius analysis, integration verification). That skill contributes WHAT to check only. Do not use its output template here — this protocol's response.md template overrides any other output-format guidance.

Use these distinctive reviewer-side phrases: I am the reviewer agent, read request.md, reviewer agent protocol, superpowers-review respond.

Do not rely on generic review prompts here. Bare phrases like code review or perform code review are intentionally broader and may route to providing-code-review instead.

---

Steps

1. Locate the request. The user will tell you the path, e.g.: ~/.codex/superpowers-review/active/{scope}/request.md

   • If the supplied request.md path is missing or unreadable, stop and tell the user no review has been requested for that scope/path.
   • If not specified, list directories in ~/.codex/superpowers-review/active/ and ask which scope to review.

2. Read request.md completely. Note the round number, response path, and review questions.

3. Read EVERY file listed in "Files to Read Before Reviewing." This is mandatory — do not form opinions from the request's claims alone. Read the actual code/docs.

   • If a referenced file doesn't exist or can't be read, report that as a CRITICAL finding. Missing files are evidence of broken references.

4. Write response.md to the path specified in the request header. Use the template below.

---

Response Template

# Code Review Response — Round {N}

## Findings

### CRITICAL (must fix before proceeding)
F1. [file:line] Description of the issue.
    Evidence: {what you actually found in the file}
    Fix: {specific recommendation}

### WARNING (should fix, risks regression if ignored)
F2. [file:line] Description...
    Evidence: ...
    Fix: ...

### INFO (observations, optional improvements)
F3. [file:line] Description...

## Verdict: {PASS | PASS_WITH_CHANGES | FAIL}
{1-2 sentence rationale referencing specific finding numbers}

---

Severity Definitions

Level	Meaning	Examples
CRITICAL	Will break functionality, lose data, or create a security issue	Broken reference, missing file, wrong command path, data loss
WARNING	Regression risk if ignored; should fix but won't break immediately	Stale data, inconsistent naming, authority drift between docs
INFO	Style, improvement suggestions, minor observations	Verbose phrasing, optional compression, cosmetic issues

Verdict Definitions

Verdict	Meaning
PASS	All changes are correct. No findings, or only INFO-level findings that don't need action.
PASS_WITH_CHANGES	Changes are fundamentally sound, but CRITICAL/WARNING findings must be addressed before shipping.
FAIL	Fundamental approach is wrong. Not just missing details — the direction needs rethinking.

---

Key Rules

1. Read code, not claims. The request describes what the author THINKS they did. Your job is to verify what ACTUALLY happened by reading the files.
2. Verify facts, not just files. If the content makes factual claims about external system state — PR status (merged/active/abandoned), deployment status, test results, build status, ticket state — you MUST verify each claim against the system of record using available API tools. A wiki page that says "Status: Merged" is a falsifiable claim, not a stylistic choice. One API call catches it. Skipping that call is a CRITICAL review failure.
3. Every finding needs a file:line reference OR an API verification reference. No vague "the code seems off." Point to the exact location or the exact API response that contradicts the claim.
4. Evidence over opinion. Show what you found, not what you feel.
5. If a review question is unanswerable from the provided files, say so explicitly — don't guess.
6. Be harsh. The requesting agent asked for adversarial review. Earn it. Call out everything — missed edge cases, broken references, semantic drift, over-cutting, under-cutting, stale data, false claims in the request itself.
7. Don't soften your language. If something is good, say so briefly and move on. Spend your time on problems.
8. Use this file's response template. providing-code-review may inform your checklist, but its output format does not replace # Code Review Response — Round {N}.

Inbound Reference Check (MANDATORY when diff contains renames/moves/deletes)

If the diff renames, moves, or deletes ANY file:

1. Identify old paths: git diff --diff-filter=RD --name-only (or extract from the diff provided)
2. Scan the ENTIRE repo for references to each old path — not just the changed directory:

   grep -rn "old-filename" . --include="*.md" --include="*.ts" --include="*.sh" --include="*.json"
   

3. Any hit outside the changed directory is a CRITICAL finding. It means a consumer was not updated and will break.

The #1 inbound-reference failure mode is scoping the search to the directory that was refactored. Other modules, sibling skills, READMEs, config files, and test suites that reference the old paths will silently break.

If you skip this check when renames/moves/deletes are present, your review is structurally incomplete — regardless of how thorough the rest of the review is.

Incident (2026-04-07): Reviewer checked cross-refs within module-a/ but never scanned module-b/ (sibling module, same repo) which referenced old paths. Result: broken consumer shipped. The test suite had the same blind spot.

Factual Verification Checklist (MANDATORY)

Before writing your verdict, scan the reviewed content for any claims about external system state. For each claim found:

Claim Type	How to Verify
PR status (merged, active, abandoned)	Call your PR platform's API — check actual status code, not preview artifacts
Deployment status	Check CI/CD pipeline or environment state
Test results ("all tests pass")	Verify CI run or run tests locally
Ticket/issue state	Query your issue tracker API (e.g., Linear, Jira, GitHub Issues)
URL targets (links to wiki, PRs, docs)	Fetch the URL or query the API — confirm it resolves
Version numbers or dependency claims	Check the actual lockfile or package manifest
"Merged commit" references	Verify the commit exists on the target branch — some PR platforms generate preview merge commits for open PRs that do NOT indicate actual merge

If you cannot verify a factual claim (no API access, no tool available), flag it as a WARNING with the note: "Unverifiable claim — reviewer lacks access to confirm."

If you skip factual verification entirely, your review is incomplete. Period.

Failure Modes

Failure	Symptom	Recovery
Malformed request.md	Missing round number, no file list, or broken markdown structure	Report as CRITICAL finding. Don't guess intent — tell the requesting agent what's missing
Scope creep into unrelated code	Flagging pre-existing issues not touched by the diff	Restrict findings to changed files and their direct callers. Note pre-existing issues as INFO only
Stale review after fixes	Round N+1 review doesn't re-read files, just checks if Round N findings were "addressed"	Always re-read ALL files from scratch each round. New fixes can introduce new issues