---
name: project-code-review
description: Use before merging or finishing implementation to review completed work against requirements and code quality, and when receiving external review feedback. Subagent dispatch is optional; the skill works with self-review and external comments.
---

# Project Code Review

## Deterministic Entry

Plan and run `engineering.code-review` when enabled. It owns diff checking,
verification planning, and the source-bound review request. This skill owns
review judgment, severity, and communication, not those mechanics.

Adapted from Superpowers by Jesse Vincent, MIT licensed:
https://github.com/obra/superpowers

Use this skill to catch issues before they cascade and to handle feedback
without performative agreement or blind implementation.

## When To Request Review

**Before:**
- Marking an `IMP-TASK-*` complete.
- Creating a PR or merging a branch.
- Claiming an `EV-*` for a significant change.

**Also useful:**
- When stuck (fresh perspective).
- After fixing a complex bug.

## Self-Review Process

### Step 1: Read The Requirements

Load the source that justifies the work:

- Approved `PRD-*` items.
- Accepted `REQ-*` records.
- `IMP-TASK-*` and `IMP-VAL-*` from the implementation plan.
- `HLT-*` health findings the work should resolve.

### Step 2: Inspect The Diff

```bash
git diff <base-sha>..<head-sha>
```

If the change is large, use host-agent diff tools or read files with offsets.

### Step 3: Evaluate

| Area | Questions |
| --- | --- |
| Plan alignment | Does the code match the approved plan? Are deviations justified? |
| Code quality | Clean separation? Proper error handling? DRY without premature abstraction? |
| Architecture | Sound design? Reasonable performance? Security considered? |
| Testing | Tests verify real behavior? Edge cases covered? All tests pass? |
| Efficiency | Can the same verified result be achieved with less code, fewer files, less state, or fewer abstractions without reducing scope? |
| Production readiness | Backward compatibility? Docs updated? No obvious bugs? |
| PRD Plugin hygiene | IDs updated? `EV-*`, `CHG-*`, `TRK-*` linked correctly? |

### Step 4: Categorize Findings

Use severity:

- **Critical**: bugs, security risks, broken functionality, missing required
  behavior.
- **Important**: architecture problems, poor error handling, test gaps.
- **Minor**: style, polish, optional improvements.

### Step 5: Record And Act

- Fix critical issues before claiming completion.
- Fix important issues before merge/PR unless explicitly accepted as follow-up.
- Note minor issues for later or ignore if out of scope.
- Record review outcome in `EV-*` or as a `HLT-*` if issues remain unresolved.

## Optional Subagent Review

Use subagents only when the user explicitly requested subagents or parallel
agent work. Host support, a generic request to review or audit, or a desire to
work faster is not permission. Use the smallest sufficient number. Use at most three
child agents total. Give each child a bounded review assignment; subagents
must not spawn subagents or delegate further.

When that explicit request exists, dispatch reviewers with:

- Description of what changed.
- Requirements or plan text.
- Base and head SHAs.
- Expected output format: Strengths, Issues (Critical/Important/Minor),
  Recommendations, Assessment (Ready to merge? Yes/No/With fixes).

Without that explicit request, or if subagents are unavailable, perform the
self-review above and document the result as `EV-*`.

## Receiving External Review Feedback

### Response Pattern

```text
1. READ complete feedback without reacting.
2. UNDERSTAND: restate the requirement or ask for clarification.
3. VERIFY: check against the codebase.
4. EVALUATE: is it technically sound for this codebase?
5. RESPOND: technical acknowledgment or reasoned pushback.
6. IMPLEMENT: one item at a time, test each.
```

### Forbidden Responses

Do not use performative agreement:

- ❌ "You're absolutely right!"
- ❌ "Great point!"
- ❌ "Thanks for catching that!"

Use instead:

- ✅ "Fixed. [Brief description of what changed]"
- ✅ "Good catch - [specific issue]. Fixed in [location]."
- ✅ "Checking... this API needs backward compat. Need to keep legacy path or
      drop pre-X support?"

### Clarify Before Implementing

If any feedback item is unclear, stop and ask for clarification on those items
before implementing others.

### YAGNI Check

If a reviewer suggests "implementing properly":

1. Grep the codebase for actual usage.
2. If unused, propose removal instead of expansion.
3. If used, implement properly.

### When To Push Back

Push back when the suggestion:

- Breaks existing functionality.
- Lacks full context.
- Violates YAGNI.
- Is technically incorrect for this stack.
- Conflicts with prior architectural decisions.

Push back with technical reasoning, not defensiveness. Involve the user if the
issue is architectural.

### Implementation Order

1. Clarify unclear items first.
2. Fix blocking issues (breaks, security).
3. Fix simple fixes (typos, imports).
4. Fix complex items (refactoring, logic).
5. Test each fix individually.
6. Verify no regressions.

## PRD Plugin Hooks

- Record the review as `EV-*` with the source plan/req IDs.
- Update `TRK-*` status only after critical/important issues are resolved.
- Add `CHG-*` if the review leads to material changes.
- Use `project-blocker-resolution` if the reviewer requests something out of
  scope, unsafe, or requiring user authority.

## Staleness Coverage

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


Before reviewing, confirm the source `PRD-*`, `REQ-*`, `IMP-TASK-*`, or `HLT-*`
has not gone stale. If the review is for an old branch or stale request, refresh
it with current evidence or record the stale risk as a `HLT-*` before acting on
the findings.

## Output Shape

When reporting review work, include:

1. Scope reviewed (files, SHAs).
2. Findings by severity.
3. Actions taken.
4. New or updated `EV-*`, `CHG-*`, `HLT-*`, or `TRK-*` records.
5. Whether the work is ready to merge, needs fixes, or is blocked.