Requesting Code Review: Catch Issues Before They Cascade
Introduction: The Review You Skip Is the Bug You Ship
Every engineer has lived this scene: you finish a feature, squint at the diff yourself, shrug “looks fine,” merge — and three commits later the flaw you waved past detonates something you didn’t touch. The Superpowers requesting code review skill exists to make that scene rarer, not by writing better code, but by formalizing the moment you ask someone — or something — else to look at your work while it is still cheap to fix.
Under Superpowers, that “someone else” is usually a dispatched reviewer subagent with one job: evaluate the work product against the requirements and report findings. The skill defines what goes into the review request, when to make one, and what to do with the answer. It is the review side of a discipline that runs through the whole series: verify early, verify often, and never let one agent grade its own homework.
What the Requesting Code Review Skill Actually Does
The skill is one paragraph of principle wrapped in a working procedure. The principle: review early, review often. The procedure: dispatch a code reviewer subagent with precisely crafted context — never your session’s history — get structured findings back, and act on them by severity.
The two halves matter equally. The dispatch catches issues before they cascade into downstream work. The context discipline is what makes the review good. A reviewer handed your entire conversation inherits your blind spots, your sunk-cost attachment to the approach, and a context window full of everything except a fresh pair of eyes. A reviewer handed a tight brief — what you built, what it should do, and exactly which commits changed — evaluates the work product, not your thought process. That distinction is the whole design.
The skill lives in software-development/superpowers-requesting-code-review, and its SKILL.md states the core principle up front: the reviewer gets precisely crafted context for evaluation — never your session’s history.
When to Request Review
The skill splits review triggers into mandatory and optional-but-valuable, and the split is worth adopting verbatim:
| Trigger | Status |
|---|---|
| After each task in subagent-driven development | Mandatory |
| After completing a major feature | Mandatory |
| Before merge to main | Mandatory |
| Each complex change or risky refactor | Strongly recommended |
| After fixing a complex bug | Optional but valuable |
| When stuck (fresh perspective) | Optional but valuable |
| Before refactoring (baseline check) | Optional but valuable |
Notice the cadence: this is not a pre-release gate. In the subagent-driven-development workflow, every single task gets reviewed the moment it completes — the unit of review is the task, not the release. The economics justify the frequency: a finding on task two costs a ten-minute fix; the same finding discovered after task eight is a rewrite, because tasks three through seven were quietly built on top of it. Review is cheap early and ruinous late, which is exactly the curve you want to be exploiting.
The Anatomy of a Review Request
This is where the skill earns its keep. A review request is not “take a look.” It is a structured brief built from four placeholders in a reviewer template, and behind them sit three things every good request includes: changes made, tests run, and edge cases considered.
1. Changes made — pinned to SHAs. The reviewer needs to know exactly what to look at, expressed in the only language git speaks:
BASE_SHA=$(git rev-parse HEAD~1) # or: git merge-base origin/main HEAD
HEAD_SHA=$(git rev-parse HEAD)
Two SHAs make the review scope mathematical: git diff BASE_SHA..HEAD_SHA is the work, nothing more, nothing less. “The recent changes” is a scavenger hunt; a commit range is a spec.
2. What it should do — the requirements, not the narrative. The template’s {PLAN_OR_REQUIREMENTS} slot takes the acceptance criteria — a task from the plan file, a ticket, a spec section. This is what the reviewer grades against. Omit it and you get an opinion; include it and you get a verdict.
3. Evidence — tests run and edge cases considered. The request states which tests were executed and what they covered, and names the edge cases you thought about (and the ones you didn’t). This is the part most humans skip and most reviewers prize: it lets the reviewer spend effort where your confidence ran out instead of rediscovering your happy path.
The dispatch then fills the template and hands it to a general-purpose subagent:
DESCRIPTION: What you built, in two sentences
PLAN_OR_REQUIREMENTS: What it should do (plan task, spec, ticket)
BASE_SHA: Starting commit
HEAD_SHA: Ending commit
Only the findings come back to the coordinator. The diff, the test output, and the evaluation all live in the reviewer’s context — which is precisely the point, as the skill’s table of common rationalizations spells out:
| Excuse | Reality |
|---|---|
| “I’ll just review the diff myself instead of dispatching a reviewer.” | You’re the coordinator — burning your context window on the diff costs you the context you need to keep driving. Dispatch the reviewer: the diff and the evaluation live in its context, and only the findings come back. |
| “The reviewer needs my whole session history to understand the change.” | Hand it precisely crafted context, never your history. That keeps the reviewer on the work product, not your thought process. |
Acting on the Answer
A review request without a triage contract is decoration. The skill prescribes severity-banded responses: Critical issues get fixed immediately; Important issues get fixed before proceeding to the next task; Minor issues get noted for later. And one rule cuts both ways: push back if the reviewer is wrong — with technical reasoning, code, or tests that prove it, never with annoyance. Arguing with valid feedback is a red flag; so is proceeding with unfixed Important issues because the schedule is tight.
Real Example: Reviewing the Article Series Plan
The series you’re reading is itself a plan executed under Superpowers: docs/superpowers/plans/2026-11-06-article-series.md defines nineteen self-contained HTML articles built from a shared template. That plan ships with a “Review Focus” section — per-article requirements the reviewer grades against: 1,200–2,000 words for deep-dives, a clear “what this skill does / when to use it / real example” structure, a code or command example, SEO head enrichment (meta description, og:image), internal links to related-skill articles, and LF newlines verified at the byte level.
Here is what a requesting-code-review pass looks like on that work, following the skill’s own transcript pattern. Instead of the writing agent re-reading its own articles — reviewing the diff inline would torch the coordinator’s context — it pins the range and dispatches:
BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | cut -d' ' -f1)
HEAD_SHA=$(git rev-parse HEAD)
DESCRIPTION: Four deep-dive articles written from the
shared template (brainstorming, writing-plans,
executing-plans, parallel-agents)
PLAN_OR_REQUIREMENTS: Review Focus section of
docs/superpowers/plans/2026-11-06-article-series.md
BASE_SHA: a7981ec
HEAD_SHA: 3df7661
The skill’s canonical example has exactly this shape — a review of “Added verifyIndex() and repairIndex() with 4 issue types” against “Task 2 from the deployment plan,” returning: strengths (clean architecture, real tests), one Important issue (missing progress indicators), one Minor (magic number 100), assessment “ready to proceed.” The Important issue gets fixed before task three starts; the magic number goes on the later list. Same loop, same discipline, whether the artifact is an index-repair module or an HTML article: the reviewer checks word count against the constraint, greps the head for the meta description, confirms internal links resolve, and counts carriage returns to catch the one Windows failure mode that would silently break deployment. Findings come back banded by severity; the coordinator fixes and moves on with its context intact.
What Makes a Review Request Good
Three adjectives, and each kills a specific failure mode:
- Clear — the reviewer knows what kind of verdict to render. Requirements in, criteria out. “Is this ready to proceed?” beats “thoughts?”
- Specific — a SHA range, not a vibe; a named plan task, not “the usual stuff.” Specific scope is also what keeps the review affordable enough to run after every task.
- Evidence-backed — tests run, edge cases considered, verification output included. A request that admits which edge cases weren’t covered is the strongest signal of a mature author and the fastest route to a useful review.
Related Deep Dives in the Series
The requesting-code-review skill is one half of a handshake:
- receiving-code-review is the other half — how the receiver evaluates feedback technically instead of performatively agreeing or defensively pushing back.
- finishing-a-development-branch is where review findings get finally reconciled before merge, PR, or discard.
- subagent-driven-development makes review mandatory after every task, with spec-compliance and quality reviewers in two stages.
- verification-before-completion supplies the evidence a good request is made of: fresh test output, not memory.
Frequently Asked Questions
Q: Isn’t reviewing after every task wasteful?
It’s the cheapest review you will ever buy. The reviewer subagent runs while the coordinator holds its context, findings on a two-commit diff take minutes to fix, and the alternative — one giant pre-merge review — is the format that reliably finds nothing because nobody can hold 900 files in working memory.
Q: What if the reviewer flags something I know is wrong?
Push back, technically. Show the code or tests that disprove the finding, or ask the reviewer to clarify what it saw. The skill lists “argue with valid technical feedback” as a red flag — the distinction is valid: disagreement with evidence is a review conversation, disagreement with mood is a process failure.
Q: Does this work for non-code artifacts?
Completely. The example above reviewed HTML articles against a plan’s Review Focus section. The method — pinned scope, explicit criteria, evidence attached, severity-banded findings — is artifact-agnostic, which is why the skill also tells you to request review when you’re stuck: a fresh evaluator of prose has the same value as one of Python.
Key Takeaways
- The Superpowers requesting code review skill formalizes the ask: pinned SHA range, explicit requirements, evidence of tests and edge cases, findings returned by severity.
- The reviewer gets crafted context, never session history — work product over thought process, and only findings return to the coordinator.
- Mandatory triggers: every task in subagent-driven development, every major feature, before merge to main. Review early, review often, because findings compound.
- Fix Critical immediately, Important before continuing, note Minor, and push back on wrong findings with reasoning, not resistance.
- A good request is clear, specific, and evidence-backed — which is also the exact recipe for making reviews useful instead of tedious.
Next in this series: receiving code review — what to do when the findings come back and you disagree. Browse the full Skills We Use series index for all nineteen articles.