How Superpowers Code Review Workflow Catches Issues Early
The Problem with Self-Review
I shipped a bug to production last month. The code looked correct to me. I had written it, tested it, and reviewed it myself. But I missed something obvious—an edge case where a null value propagated through the system.
The issue wasn’t my testing. It was my review process. When I review my own code, I see what I intended to write, not what I actually wrote. Fresh eyes catch what tired eyes miss.
This is why Superpowers has a dedicated code review workflow. Not a checklist. Not a linting step. An actual independent reviewer that examines code with fresh context.
What Is the Code Review Skill?
The requesting-code-review skill dispatches a code-reviewer subagent with precisely crafted context—never the main session’s history. The reviewer examines changes between two git commits and classifies issues by severity:
- Critical: Blocks progress. Must fix immediately.
- Important: Should fix before proceeding.
- Minor: Note for later cleanup.
The core principle is simple:
Review early, review often.
This isn’t optional polish. It’s a structural part of the development workflow.
When to Request Review
I’ve learned to request review at specific moments:
Mandatory reviews:
- After each task in subagent-driven development
- After completing a major feature
- Before merging to main
Optional but valuable:
- When stuck (fresh perspective helps)
- Before refactoring (establish baseline)
- After fixing a complex bug
┌─────────────────────────────────────────────┐│ Development Flow │└─────────────────────┬───────────────────────┘ │ ▼┌─────────────────────────────────────────────┐│ Complete a task │└─────────────────────┬───────────────────────┘ │ ▼ ┌─────────────────────────┐ │ Request code review │ └────────────┬────────────┘ │ ┌──────────┴──────────┐ │ │ ▼ ▼ ┌───────────┐ ┌───────────┐ │ Issues? │ │ Issues? │ │ Critical │ │ Important │ └─────┬─────┘ └─────┬─────┘ │ │ ▼ ▼ ┌───────────┐ ┌───────────┐ │ BLOCKED │ │ FIX NOW │ │ Must fix │ │ Then │ │ first │ │ continue │ └───────────┘ └───────────┘Notice the difference: Critical issues block everything. Important issues need fixes but don’t require re-review. Minor issues are noted and addressed later.
How to Request Review
The process requires two git SHAs—the starting point and ending point of the work to review.
Step 1: Get the Git SHAs
# Option A: Review last commitBASE_SHA=$(git rev-parse HEAD~1)HEAD_SHA=$(git rev-parse HEAD)
# Option B: Review against main branchBASE_SHA=$(git rev-parse origin/main)HEAD_SHA=$(git rev-parse HEAD)
# Option C: Review specific commit rangeBASE_SHA=a7981ecHEAD_SHA=3df7661The base SHA defines where the review starts. Everything after that commit (up to HEAD_SHA) gets examined.
Step 2: Dispatch the Reviewer
I use the Task tool to dispatch a code-reviewer subagent with specific context:
WHAT_WAS_IMPLEMENTED: Verification and repair functionsPLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.mdBASE_SHA: a7981ecHEAD_SHA: 3df7661DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue typesThe reviewer receives exactly this context. Not my session history. Not my thought process. Just the work product and what it should do.
Step 3: Act on Feedback
The reviewer returns with strengths and issues:
Strengths:- Clean architecture with clear separation of concerns- Real tests with meaningful assertions- Good error handling
Issues: Important: Missing progress indicators for long operations Minor: Magic number (100) for reporting interval
Assessment: Ready to proceed after fixing Important issueI then:
- Fix Important issues before continuing
- Note Minor issues for later
- Push back if the reviewer is wrong (with reasoning)
Why Fresh Subagent Matters
The reviewer gets precisely crafted context—not my session’s history. This matters for three reasons:
Focus on work product, not thought process
My session history contains dead ends, experiments, and partial understandings. The reviewer doesn’t need any of that. It needs the final work and the requirements.
Preserved context for continued work
My main session keeps its context. I don’t lose my mental model of the overall project. The reviewer operates independently.
Independent assessment
When I review my own code, I’m biased. A fresh subagent sees the code objectively. It doesn’t know what I “meant” to do. It sees what I actually did.
┌─────────────────────────────────────────────────────┐│ Main Session ││ ││ ┌────────────────┐ ┌────────────────────────┐ ││ │ Full context │ │ Work product │ ││ │ of project │ │ (git diff) │ ││ └────────┬───────┘ └───────────┬────────────┘ ││ │ │ ││ │ │ ││ ▼ ▼ ││ ┌────────────────┐ ┌────────────────────────┐ ││ │ Continue │ │ Dispatch reviewer │ ││ │ working │ │ subagent │ ││ └────────────────┘ └────────────────────────┘ ││ │ │└────────────────────────────────────│─────────────────┘ │ ┌───────────┴───────────┐ │ │ ▼ │ ┌────────────────┐ │ │ Reviewer │ │ │ Subagent │ │ │ │ │ │ Fresh context: │ │ │ - What changed │ │ │ - Requirements │ │ │ - No history │ │ └───────┬────────┘ │ │ │ ▼ │ ┌────────────────┐ │ │ Review output │───────────────┘ │ - Strengths │ │ - Issues │ │ - Assessment │ └────────────────┘A Real Review Session
Here’s what an actual review session looks like:
[Just completed Task 2: Add verification functions]
# Get commit rangeBASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')HEAD_SHA=$(git rev-parse HEAD)
# Dispatch reviewer[Task tool: superpowers:code-reviewer] WHAT_WAS_IMPLEMENTED: Verification and repair functions PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md BASE_SHA: a7981ec HEAD_SHA: 3df7661 DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
# Reviewer returns:Strengths:- Clean function structure- Good test coverage for happy path- Clear naming
Issues: Important: Missing progress indicators - verifyIndex() can run for minutes on large indexes - Should report progress every N items
Minor: Magic number (100) - Hardcoded in reporting interval - Should be a named constant
Assessment: Ready to proceed after addressing Important issue
# I fix the Important issue:- Added progress callback parameter- Reports every 100 items (documented the magic number)
# Continue to Task 3Notice the flow: complete task, review, fix issues, continue. The review catches problems before they compound.
Handling Reviewer Feedback
Not all feedback requires changes. I use this decision tree:
┌─────────────────────────────────────┐│ Reviewer feedback │└─────────────────┬───────────────────┘ │ ▼ ┌─────────────────┐ │ Severity? │ └────────┬────────┘ │ ┌───────────┼───────────┐ │ │ │ ▼ ▼ ▼┌─────────┐ ┌─────────┐ ┌─────────┐│Critical │ │Important│ │ Minor │└────┬────┘ └────┬────┘ └────┬────┘ │ │ │ ▼ ▼ ▼┌─────────┐ ┌─────────┐ ┌─────────┐│ BLOCK │ │ FIX │ │ NOTE ││ Fix now │ │ before │ │ later ││ Re- │ │ contin- │ │ or ││ review │ │ uing │ │ accept │└─────────┘ └─────────┘ └─────────┘Critical issues: I stop everything. Fix immediately. Re-review before continuing. These indicate fundamental problems.
Important issues: I fix before moving to the next task. No re-review needed unless the fix is complex.
Minor issues: I note them. Sometimes I fix immediately if it takes 30 seconds. Sometimes I leave a TODO. The key is not blocking progress.
When I disagree with the reviewer:
Reviewer: "Important: This function should use async/await"
Me: "The function is CPU-bound, not I/O-bound. async/await would add complexity without benefit. Keeping synchronous."
Reviewer: [Accepts reasoning or provides counter-argument]I don’t blindly accept feedback. I evaluate it. But I also don’t dismiss feedback without reasoning.
Common Mistakes
DO
Review after each task in subagent-driven development
Task 1 complete → Review → Fix issues → Task 2 complete → Review → ...This catches problems when context is fresh. Waiting until the end compounds issues.
Provide complete context to the reviewer
# GOODWHAT_WAS_IMPLEMENTED: Cache invalidation logicPLAN_OR_REQUIREMENTS: Task 3 from cache-plan.md - invalidate on writeBASE_SHA: abc123HEAD_SHA: def456DESCRIPTION: Added invalidation hooks with TTL support
# BAD - missing contextWHAT_WAS_IMPLEMENTED: Some cache stuffBASE_SHA: abc123HEAD_SHA: def456Use appropriate commit ranges
# GOOD: Review specific taskBASE_SHA=$(git log --oneline | grep "Task 2" | head -1 | awk '{print $1}')HEAD_SHA=$(git rev-parse HEAD)
# BAD: Review entire branch at onceBASE_SHA=$(git merge-base origin/main HEAD)HEAD_SHA=$(git rev-parse HEAD)# Too much to review effectivelyDON’T
Skip review for “simple” changes
Me: "This is just a one-line fix, no need to review"[One week later: Production incident from that one line]Simple changes often have non-simple implications. Review catches them.
Review your own code by self-inspection
# WRONG: Relying on self-reviewMe: "I reviewed this myself, looks good"[Pushes to main]
# CORRECT: Independent reviewerMe: [Dispatches code-reviewer subagent]Reviewer: "Important: Missing null check on line 47"Me: "Good catch, fixed"Accept “looks good” without specifics
# WRONGReviewer: "Code looks good"[No specifics = no real review]
# CORRECTReviewer: Strengths: Clear variable names, good test coverage Issues: None found Assessment: Approved[Specifics show actual review happened]Let review become a bottleneck
# WRONG: Waiting days for review[Complete task][Wait 3 days for reviewer availability][Context lost, momentum killed]
# CORRECT: Immediate review[Complete task][Dispatch subagent reviewer immediately][Fix issues while context is fresh]Integration with Other Skills
The code review skill integrates with other Superpowers workflows:
Subagent-driven development: Review after EACH task. This is non-negotiable.
After brainstorming: Spec review loop with max 3 iterations. The reviewer checks if specs match requirements.
Before finishing branch: Final code review using finishing-a-development-branch skill. This catches issues before merge.
┌─────────────────────────────────────────────────────┐│ Workflow Integration │├─────────────────────────────────────────────────────┤│ ││ Subagent-driven development: ││ Task → Implement → SPEC REVIEW → CODE REVIEW ││ ││ After brainstorming: ││ Brainstorm → SPEC REVIEW (max 3 iterations) ││ ││ Finishing branch: ││ All tasks done → FINAL CODE REVIEW → Merge ││ │└─────────────────────────────────────────────────────┘Model Selection for Reviews
I’ve found that code review benefits from more capable models:
| Review Type | Model | Reason |
|---|---|---|
| Spec compliance | Standard | Checking against requirements |
| Code quality | Capable | Needs judgment and experience |
| Security review | Most capable | Requires deep security knowledge |
| Final review before merge | Most capable | Last line of defense |
The cost difference is small compared to the cost of bugs in production.
Summary
In this post, I showed how Superpowers code review skill dispatches independent reviewer subagents with focused context to catch issues early. The key practices are:
- Review after each task in subagent-driven development
- Review after major features
- Review before merges
- Fix Critical issues immediately, Important issues before continuing, note Minor issues
- Provide complete context to reviewers
- Never skip review for “simple” changes
The fresh subagent approach means reviews are objective and focused. The main session keeps its context. The reviewer sees only what matters: the changes and the requirements.
Since adopting this workflow, I’ve caught issues I would have missed with self-review. The cost is a few minutes per task. The benefit is significantly fewer bugs reaching production.
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments