review

Review

Three modes. Pick based on scope:

========================================

Changes mode — review uncommitted changes before committing

Violating the letter of verification is violating the spirit. Partial checks prove nothing.

Do NOT approve or express satisfaction with changes until verification commands have been run and output confirms the claim.

Procedure

1. Run git status to see what's changed
2. Run git diff to see the actual changes
3. For each modified file, analyze:
   • Is the change correct and complete?
   • Are there any potential bugs?
   • Does it follow project conventions?
   • Are there any security concerns?
   • Is error handling adequate?
4. Verify claims with evidence — before expressing any positive assessment:
   • If tests exist: run them and confirm output
   • If linting is configured: run the linter and confirm clean
   • If the change fixes a bug: reproduce the original symptom and confirm it's resolved
   • Do NOT say "looks good" based on reading code alone when verification commands are available
5. Provide a summary with:
   • What looks good (with evidence from Step 4)
   • Any concerns or suggestions
   • Recommended next steps (test, commit, or make changes)

---

Red Flags — STOP

If you catch yourself thinking any of these during review, STOP — you are about to skip verification:

• "The code looks correct" — based on what? Visual inspection is not verification. Did you trace the logic path? Did you check edge cases? "Looks correct" is an opinion, not evidence.
• "Tests are probably passing" — "Probably" is not evidence. Run git diff to identify what changed, then verify that relevant tests exist and were actually executed. If you haven't seen test output, you don't know.
• "It's a small change, no need for full review" — Small changes cause production outages. A one-line typo in a config file can take down a service. Review depth scales with risk, not line count.
• "I already reviewed this mentally" — Mental review is not review. Show your work — the summary in Step 4 proves you actually analyzed each file.
• "The diff is clean" — Clean diffs can contain logic errors, missing error handling, security vulnerabilities, and broken edge cases. "Clean" means well-formatted, not correct.
• Providing a summary without mentioning a single specific file or line — Generic feedback ("looks good overall") means you didn't actually review the changes. Name files. Cite lines.
• Recommending "commit" without checking for test coverage — Untested changes are incomplete changes. If there are no tests, that IS a concern to flag.

Common Rationalizations

Excuse	Reality
"The code looks correct"	Visual inspection catches formatting, not logic. Trace the actual execution path.
"Tests are probably passing"	"Probably" = "I didn't check." Run them or confirm they were run.
"Small change, quick review"	Small change, full review — just faster. Not no review.
"I already reviewed this mentally"	Mental review has no evidence trail. Write down what you found.
"The diff is clean"	Clean != correct. Clean diffs hide logic bugs.
"It's just a refactor"	Refactors break behavior. Verify the old tests still pass.
"No security concerns here"	Did you actually check for injection, auth, and data exposure? Saying "no concerns" requires evidence.
"Error handling is adequate"	Adequate by what standard? Check every error path. What happens on null? On timeout? On malformed input?

========================================

PR mode — review a specific pull request

Structured code review on a pull request. Produce clear, actionable comments -- then post them with user approval.

Engineering Lens

Violating the letter of verification is violating the spirit. If every checklist item isn't explicitly verified with evidence, the review is incomplete.

Ground every comment in first principles, simplicity, modularity, separation of concerns, and clean implementation. Be helpful, not pedantic -- flag what matters, skip linter-level style nitpicks.

Procedure

Follow these steps exactly in order.

Step 1: Identify the PR

Accept PR number, URL, or no argument (run gh pr list and ask user to pick). Fetch with gh pr view <number> --json title,body,author,baseRefName,headRefName,files,additions,deletions,reviews,comments. Present overview (author, branch, files, status, existing reviews).

Step 2: Read the Diff

Fetch with gh pr diff <number>. Read thoroughly -- for each changed file, read enough surrounding context to understand the change in situ. For large PRs (>500 lines), organize by file or logical concern and use Explore subagents to parallelize.

Step 3: Understand Intent

Before critiquing, understand what the PR is trying to do. Read the PR body, referenced plan docs, linked issues, and commit messages. Summarize: "This PR does X because Y." Ask user to confirm if unsure.

Step 4: Review

Evaluate the PR across the dimensions defined in review-dimensions.md. Categorize each finding by severity using the system in severity-categories.md.

Do NOT post approval or positive comments until every checklist item in Step 4 has been explicitly verified with evidence. Reading code is not verification -- check CI status, confirm test coverage, trace logic through the actual codebase, and run local verification commands when the branch is available.

Step 5: Present Review

Present findings organized by severity (Blockers, Suggestions, Nits, Questions) with file:line references and concrete fixes. Include a one-sentence assessment and verdict (Approve / Request Changes / Comment Only). Follow the rules in severity-categories.md.

Step 6: Post Review

Ask user: "Want me to post this review to the PR?" Options: post as-is, edit first, or keep local. Use gh pr review <number> with --approve, --request-changes, or --comment. Post file-level comments via gh api. Confirm when posted.

Notes

• Helpful, not hostile. Phrase feedback constructively.
• Proportional depth. Scale review to the PR's scope.
• Understand before criticizing. Step 3 exists for a reason.
• Concrete suggestions always. "Replace X with Y because Z" -- not "this could be better."
• Respect the plan. If the PR follows a plan doc, review against it. Don't re-litigate approved decisions unless new evidence appears.
• Security findings are always blockers. No exceptions.
• Don't rubber-stamp. Actually check -- even good engineers miss things.

Before finalizing any review, consult red-flags-and-rationalizations.md and verify you haven't fallen into any of those traps.

========================================

Multi-PR mode — risky/critical changes or multiple PRs at once, dispatches parallel review subagents

A single reviewer has blind spots. This skill spawns four review subagents in parallel — each invokes a different review skill so the four perspectives aren't just different prompts, they're different disciplines applied to every PR. Then synthesizes.

Without it, agents default to: one merged review per PR, serial work, no claim verification, judgments instead of failure modes.

When to Use

Triggers: "thoroughly review," "defense in depth," "before merging," PRs touching production-critical paths (pipelines, deploy, auth, data DML), or multiple open PRs needing coordinated review.

Skip: trivial PRs (<20 lines), docs-only, or when you already have strong diff context.

REQUIRED SUB-SKILL: superpowers:dispatching-parallel-agents.

The Four Lenses

Each subagent invokes its assigned skill FIRST (via the Skill tool), then applies that skill's discipline to every PR in the batch.

Name	Lens	Invokes skill	Hunts for
reviewer-general	generalist	/review-pr	Correctness, design, tests, edge cases, readability
reviewer-structural	risk-class	/review (gstack)	SQL injection, LLM trust boundaries, conditional side effects, data loss, error swallowing, atomicity
reviewer-adversarial	break-it	/codex (challenge mode)	Concrete failure modes with input+severity; "200 IQ" adversarial second opinion
reviewer-spec	claim-vs-impl	superpowers:requesting-code-review	Extracts PR body claims, traces each to diff, flags mismatches, verifies work-meets-requirements

Each agent gets the full PR list — lens separation is what catches what one perspective misses.

Why this works: each review skill is a crystallized discipline. Invoking the skill means the subagent inherits that skill's checklist, ethos, and rigor — not just a lens description in a prompt. Four skills applied in parallel = four crystallized disciplines, not four paraphrases of "be thorough."

Procedure

1. Gather PRs. Accept URL, owner/repo#N, or #N. Verify each with gh pr view.

2. Compose four self-contained prompts. Each must include:

   • The lens name + ethos
   • The exact skill-invocation instruction: "FIRST: invoke the <skill> skill via the Skill tool — apply its discipline as the primary reviewing lens. Do not proceed to the PRs until the skill is loaded."
   • Every PR's owner/repo/number
   • Brief context (from gh pr view --json body)
   • Local clone paths + branches if available
   • The exact gh pr diff commands
   • Structured output format per PR
   • ~600-word cap on the synthesis output

3. Dispatch in ONE message. All four Agent calls together, subagent_type: general-purpose (required — default code-reviewer lacks Skill tool access), run_in_background: true, names from the table above. Sequential dispatch loses all parallelism.

4. Wait for all four. One-line completion announcements ("2 of 4 done"). Do NOT synthesize partial — cross-reviewer consensus is the signal.

5. Synthesize in this order:

   • Consensus table per PR — findings flagged by ≥2 reviewers: # | Finding | Reviewers | Severity. Severity floor = loudest reviewer.
   • Single-reviewer findings worth considering — specific, actionable, skip paranoia.
   • Verdict matrix — Lens | PR #A | PR #B, each reviewer's explicit verdict.
   • Must-fix list — your editorial filter with file:line.

6. Offer to act: fix, post as PR comment, or leave. Post via gh pr comment <N> --repo <owner>/<repo> --body.

Common Mistakes

Mistake	Fix
Dispatching sequentially	Single message, multiple tool calls
Forgetting to instruct skill invocation	Each prompt must include "FIRST: invoke <skill>" — otherwise the subagent improvises a review without the discipline
Using code-reviewer subagent type	It lacks Skill tool access; use general-purpose
Synthesizing before all four return	Wait — consensus IS the signal
One PR per agent	Each agent reviews EVERY PR
Softening adversarial low-severity items	Preserve severity; user decides
Description summarizing workflow	Description = triggering conditions only
Assigning multiple skills per agent	One skill per agent — discipline concentration is the point

========================================

Migration

Consolidated from legacy skills. Pick the mode/lens based on intent.