Code Reviewer
Two responsibilities: requesting review (dispatching a reviewer subagent) and receiving review (acting on feedback with technical rigor). Review early, review often. Verify before implementing feedback.
Part 1: Requesting Review
Mandatory after: each task in SDD, each planned execution wave, each major feature, before merge.
Optional: when stuck, before refactoring, after fixing complex bugs.
Procedure
- Get SHAs:
BASE_SHA=$(git rev-parse HEAD~1) and HEAD_SHA=$(git rev-parse HEAD)
- Dispatch
general-purpose subagent using template at skills/code-reviewer/code-reviewer-prompt.md
- Fill placeholders:
[DESCRIPTION] (what was built), [PLAN_OR_REQUIREMENTS] (contract/spec reference), [BASE_SHA], [HEAD_SHA], [WAVE_ID], and a distinct [REVIEW_REPORT_FILE].
- Require the reviewer to write a non-empty persisted review report at
.superpowers/sdd/reviews/<wave-id>.md, then record that exact in-overlay path in the wave receipt with ssf execution review <change-dir> --wave <wave-id> --base <base-sha> --head <head-sha> --report .superpowers/sdd/reviews/<wave-id>.md --verdict <pass|fail>. The execution plan initializes this directory; paths outside it are rejected for audit safety.
- Act on feedback: Critical/Important findings require a
fail receipt, focused repair, re-review, and replacement pass receipt before a dependent wave or closing can proceed. Note Minor for later, push back with reasoning if reviewer is wrong.
- At
adjudication-required, wait for a human to run ssf execution adjudicate <change-dir> --wave <id> --decision allow-review --confirm --reason <text> before another review. It authorizes one review and never substitutes for pass.
Minimality And Scope
For unrequested complexity, cite the missing task requirement and diff line.
Use Important for merge-blocking complexity and Minor for safe,
behavior-neutral redundancy; never score by line count.
Part 2: Receiving Review Feedback
The Response Pattern
- READ feedback without reacting
- UNDERSTAND and restate requirement
- VERIFY against codebase reality
- EVALUATE: technically sound for THIS codebase?
- RESPOND: technical acknowledgment or reasoned pushback
- IMPLEMENT: one item at a time, test each
Severity Levels
| Level |
Meaning |
Action |
| Critical |
Bugs, security, data loss, broken functionality |
Fix immediately |
| Important |
Architecture problems, missing features, poor error handling, test gaps |
Fix before next batch |
| Minor |
Code style, optimization, documentation polish |
Note for later |
Forbidden Responses
Never: performative agreement ("You're right!", "Great point!"), blind implementation before verification, thanking the reviewer. Instead: restate the requirement, ask clarifying questions, push back with reasoning, or just fix it (actions > words).
Handling Unclear Feedback
If any item is unclear → STOP. Do not implement anything yet. Ask for clarification on unclear items. Partial understanding = wrong implementation.
Source-Specific Rules
From user: Trusted — implement after understanding. Still ask if scope unclear. No performative agreement.
From external reviewer: Before implementing, check: technically correct for this codebase? breaks existing functionality? reason for current implementation? works on all platforms? reviewer understands full context? If suggestion seems wrong, push back with technical reasoning.
When to Push Back
Suggestion breaks existing functionality, reviewer lacks context, violates YAGNI, technically incorrect for this stack, legacy/compatibility reasons, conflicts with user's architectural decisions. Push back with technical reasoning, not defensiveness.
Implementation Order
- Clarify unclear items first
- Fix blocking issues (breaks, security)
- Fix simple issues (typos, imports)
- Fix complex issues (refactoring, logic)
- Test each fix individually, verify no regressions
Common Mistakes
| Mistake |
Fix |
| Performative agreement |
State requirement or just act |
| Blind implementation |
Verify against codebase first |
| Batch without testing |
One at a time, test each |
| Proceeding without a wave receipt |
Record pass/fail via ssf execution review before the next dependent wave |
| Assuming reviewer is right |
Check if breaks things |
| Avoiding pushback |
Technical correctness > comfort |
| Partial implementation |
Clarify all items first |
Exception Handling
- Parse failures: Report specific file, request regenerated review package
- Missing files: Regenerate via
scripts/review-package. Empty diff = nothing to review
- User interruption: Re-read review report on resume, continue from next unreviewed batch
Standard User-Facing Handoff
End every user-facing phase report with this concise handoff. Only a successfully
persisted closing state and abandoned are terminal.
Normal report
- Current stage:
<detected workflow stage>.
- Completed / blocker:
<completed work>.
- Next stage:
<next workflow stage or skill>.
- Entry condition:
<what must be true to enter it>.
Blocked report
- Current stage:
<detected workflow stage>.
- Completed / blocker:
<blocking fact or missing evidence>.
- Next stage:
<stage that resumes after the blocker>.
- Entry condition:
<the approval, artifact, validation, or fix required>.
Approval-wait report
- Current stage:
<detected workflow stage>.
- Completed / blocker:
<work ready for the named decision>.
- Next stage:
<stage that follows approval>.
- Entry condition:
<explicit user approval or recorded decision>.
Successful terminal report
- Current stage: successfully persisted
closing or abandoned.
- Completed / blocker:
<persisted terminal outcome>.
- Next stage:
none.
- Entry condition: no further transition exists.
1---2name: code-reviewer3description: Review completed implementation batches for spec compliance and code quality. Invoke after execution batches complete, before merging, or when a review gate is reached in the workflow.4---56# Code Reviewer78Two responsibilities: requesting review (dispatching a reviewer subagent) and receiving review (acting on feedback with technical rigor). **Review early, review often. Verify before implementing feedback.**910## Part 1: Requesting Review1112**Mandatory after**: each task in SDD, each planned execution wave, each major feature, before merge.13**Optional**: when stuck, before refactoring, after fixing complex bugs.1415### Procedure161. Get SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`172. Dispatch `general-purpose` subagent using template at `skills/code-reviewer/code-reviewer-prompt.md`183. Fill placeholders: `[DESCRIPTION]` (what was built), `[PLAN_OR_REQUIREMENTS]` (contract/spec reference), `[BASE_SHA]`, `[HEAD_SHA]`, `[WAVE_ID]`, and a distinct `[REVIEW_REPORT_FILE]`.194. Require the reviewer to write a non-empty persisted review report at `.superpowers/sdd/reviews/<wave-id>.md`, then record that exact in-overlay path in the wave receipt with `ssf execution review <change-dir> --wave <wave-id> --base <base-sha> --head <head-sha> --report .superpowers/sdd/reviews/<wave-id>.md --verdict <pass|fail>`. The execution plan initializes this directory; paths outside it are rejected for audit safety.205. Act on feedback: Critical/Important findings require a `fail` receipt, focused repair, re-review, and replacement `pass` receipt before a dependent wave or closing can proceed. Note Minor for later, push back with reasoning if reviewer is wrong.216. At `adjudication-required`, wait for a human to run `ssf execution adjudicate <change-dir> --wave <id> --decision allow-review --confirm --reason <text>` before another review. It authorizes one review and never substitutes for `pass`.2223### Minimality And Scope2425For unrequested complexity, cite the missing task requirement and diff line.26Use Important for merge-blocking complexity and Minor for safe,27behavior-neutral redundancy; never score by line count.2829## Part 2: Receiving Review Feedback3031### The Response Pattern321. READ feedback without reacting332. UNDERSTAND and restate requirement343. VERIFY against codebase reality354. EVALUATE: technically sound for THIS codebase?365. RESPOND: technical acknowledgment or reasoned pushback376. IMPLEMENT: one item at a time, test each3839### Severity Levels4041| Level | Meaning | Action |42|-------|---------|--------|43| Critical | Bugs, security, data loss, broken functionality | Fix immediately |44| Important | Architecture problems, missing features, poor error handling, test gaps | Fix before next batch |45| Minor | Code style, optimization, documentation polish | Note for later |4647### Forbidden Responses48Never: performative agreement ("You're right!", "Great point!"), blind implementation before verification, thanking the reviewer. Instead: restate the requirement, ask clarifying questions, push back with reasoning, or just fix it (actions > words).4950### Handling Unclear Feedback51If any item is unclear → STOP. Do not implement anything yet. Ask for clarification on unclear items. Partial understanding = wrong implementation.5253### Source-Specific Rules5455**From user**: Trusted — implement after understanding. Still ask if scope unclear. No performative agreement.5657**From external reviewer**: Before implementing, check: technically correct for this codebase? breaks existing functionality? reason for current implementation? works on all platforms? reviewer understands full context? If suggestion seems wrong, push back with technical reasoning.5859### When to Push Back60Suggestion breaks existing functionality, reviewer lacks context, violates YAGNI, technically incorrect for this stack, legacy/compatibility reasons, conflicts with user's architectural decisions. Push back with technical reasoning, not defensiveness.6162### Implementation Order631. Clarify unclear items first642. Fix blocking issues (breaks, security)653. Fix simple issues (typos, imports)664. Fix complex issues (refactoring, logic)675. Test each fix individually, verify no regressions6869## Common Mistakes7071| Mistake | Fix |72|---------|-----|73| Performative agreement | State requirement or just act |74| Blind implementation | Verify against codebase first |75| Batch without testing | One at a time, test each |76| Proceeding without a wave receipt | Record `pass`/`fail` via `ssf execution review` before the next dependent wave |77| Assuming reviewer is right | Check if breaks things |78| Avoiding pushback | Technical correctness > comfort |79| Partial implementation | Clarify all items first |8081## Exception Handling8283- **Parse failures**: Report specific file, request regenerated review package84- **Missing files**: Regenerate via `scripts/review-package`. Empty diff = nothing to review85- **User interruption**: Re-read review report on resume, continue from next unreviewed batch8687## Standard User-Facing Handoff8889End every user-facing phase report with this concise handoff. Only a successfully90persisted `closing` state and `abandoned` are terminal.9192### Normal report9394- Current stage: `<detected workflow stage>`.95- Completed / blocker: `<completed work>`.96- Next stage: `<next workflow stage or skill>`.97- Entry condition: `<what must be true to enter it>`.9899### Blocked report100101- Current stage: `<detected workflow stage>`.102- Completed / blocker: `<blocking fact or missing evidence>`.103- Next stage: `<stage that resumes after the blocker>`.104- Entry condition: `<the approval, artifact, validation, or fix required>`.105106### Approval-wait report107108- Current stage: `<detected workflow stage>`.109- Completed / blocker: `<work ready for the named decision>`.110- Next stage: `<stage that follows approval>`.111- Entry condition: `<explicit user approval or recorded decision>`.112113### Successful terminal report114115- Current stage: successfully persisted `closing` or `abandoned`.116- Completed / blocker: `<persisted terminal outcome>`.117- Next stage: `none`.118- Entry condition: no further transition exists.
magebyte-zero