# Plan-Anchored Code Review & Feedback

> The final "QA Review" step: checking implementation against the original plan and spec, reporting issues by severity, and ensuring a high bar for PR acceptance.

- Repository: obra/superpowers
- GitHub: https://github.com/obra/superpowers
- Human wiki: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85
- Complete Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/llms-full.txt

## Source Files

- `skills/requesting-code-review/SKILL.md`
- `skills/receiving-code-review/SKILL.md`
- `skills/requesting-code-review/code-reviewer.md`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [skills/requesting-code-review/SKILL.md](skills/requesting-code-review/SKILL.md)
- [skills/receiving-code-review/SKILL.md](skills/receiving-code-review/SKILL.md)
- [skills/requesting-code-review/code-reviewer.md](skills/requesting-code-review/code-reviewer.md)
- [skills/subagent-driven-development/SKILL.md](skills/subagent-driven-development/SKILL.md)
- [skills/subagent-driven-development/spec-reviewer-prompt.md](skills/subagent-driven-development/spec-reviewer-prompt.md)
- [skills/subagent-driven-development/code-quality-reviewer-prompt.md](skills/subagent-driven-development/code-quality-reviewer-prompt.md)
- [docs/superpowers/specs/2026-01-22-document-review-system-design.md](docs/superpowers/specs/2026-01-22-document-review-system-design.md)
</details>

# Plan-Anchored Code Review & Feedback

Plan-Anchored Code Review is the final "QA Review" stage in the Superpowers workflow, ensuring that every implementation not only meets high technical standards but also aligns perfectly with the original specification and implementation plan. By anchoring reviews to a verified plan, the system prevents "scope creep" and "drift" where an implementation solves the wrong problem or adds unrequested complexity.

This process utilizes specialized subagents to perform objective evaluations. This approach preserves the lead agent's context for coordination while providing a fresh, skeptical perspective on the work product. The primary goal is to catch issues before they cascade into more complex technical debt or architectural failures.

## The Two-Stage Review Process

In subagent-driven development, every task undergoes a mandatory two-stage review process before it is considered complete. This ensures that functional requirements are met before technical polish is evaluated.

### Stage 1: Spec Compliance Review
The first gate focuses exclusively on whether the implementation matches the requested task or specification—nothing more and nothing less. The reviewer is instructed to be skeptical and verify claims by reading the actual code rather than trusting the implementer's report.

| Category | Goal |
| :--- | :--- |
| **Missing Requirements** | Ensure every line-item in the spec was actually implemented. |
| **Extra/Unneeded Work** | Flag over-engineering, "nice-to-haves," or features not in the spec (YAGNI). |
| **Misunderstandings** | Check for misinterpretations of the requirement's intent. |

Sources: [skills/subagent-driven-development/spec-reviewer-prompt.md:5-56]()

### Stage 2: Code Quality Review
Once an implementation is verified as spec-compliant, it moves to the quality gate. This stage evaluates the technical health of the code, its architecture, and its readiness for production.

- **Architecture:** Checks for clean separation of concerns and sound design decisions.
- **Error Handling:** Verifies proper handling of edge cases and failures.
- **Testing:** Ensures tests verify real behavior (avoiding brittle mocks) and that all tests pass.
- **Production Readiness:** Considers backward compatibility and documentation completeness.

Sources: [skills/requesting-code-review/code-reviewer.md:11-64](), [skills/subagent-driven-development/code-quality-reviewer-prompt.md:5-23]()

## Reporting Issues by Severity

Reviewers categorize findings into three distinct severity levels to help the implementer prioritize fixes.

1.  **Critical (Must Fix):** Serious bugs, security vulnerabilities, data loss risks, or fundamentally broken functionality.
2.  **Important (Should Fix):** Architectural issues, missing requested features, poor error handling, or significant test gaps.
3.  **Minor (Nice to Have):** Code style nitpicks, small optimization opportunities, or documentation polish.

Sources: [skills/requesting-code-review/code-reviewer.md:83-90]()

## The Feedback Loop & Reception

Code review is a technical protocol, not a social performance. Superpowers enforces a "Technical Rigor Over Social Comfort" principle.

- **Verify Before Implementing:** The agent must read the feedback, restate the requirement, and check it against codebase reality before acting.
- **No Performative Agreement:** Expressions like "You're absolutely right!" or "Great point!" are forbidden. The agent should acknowledge the fix factually (e.g., "Fixed in [location]") or push back with technical reasoning.
- **Reasoned Pushback:** If a reviewer lacks context or suggests a change that violates project principles (like YAGNI), the agent must push back using technical evidence.

```mermaid
sequenceDiagram
    participant I as Implementer
    participant R as Reviewer (Subagent)
    I->>R: Dispatch with Plan + Code Range
    Note over R: Review Stage 1: Spec Compliance
    R-->>I: Issues (if any)
    I->>I: Fix Spec Gaps
    I->>R: Re-Review Stage 1
    Note over R: Review Stage 2: Code Quality
    R-->>I: Severity-Categorized Issues
    I->>I: Fix Issues (High Severity First)
    I->>R: Final Verification
    R-->>I: Ready to Merge / Approved
```

Sources: [skills/receiving-code-review/SKILL.md:10-128]()

## Workflow Integration

Plan-Anchored review is mandatory at several key checkpoints in the development lifecycle:
- **Task Completion:** Review after every individual task in a plan to catch issues before they compound.
- **Feature Completion:** A final "whole-implementation" review after all tasks are finished.
- **Merge Preparation:** Before any branch is merged into the main codebase.

Sources: [skills/requesting-code-review/SKILL.md:14-23](), [skills/subagent-driven-development/SKILL.md:8-12]()

The system remains provider-neutral and portable, treating review subagents as specialized functions that can be dispatched regardless of the underlying model provider or repository structure.

Sources: [skills/subagent-driven-development/SKILL.md:238-250]()