polyflow-review

name	polyflow-review
description	Code review — both giving and receiving feedback. Verifying observed behavior over performative agreement. Use when reviewing a PR, requesting review on completed work, or processing review feedback you received.

PolyFlow: Review

Vocabulary

See polyflow meta-skill.

When to Use

• Completed work, want a review pass before integration
• Reviewing someone else's PR
• Received review feedback and need to process it (especially if you disagree)

Two Halves

A. Requesting Review (giving work to be reviewed)

1. Self-review first

Before asking anyone to look:

• Run the project's configured quality checks (for example typecheck, lint, test, or build)
• Re-read the diff with fresh eyes
• Check the diff matches the spec/plan — no scope creep
• Look for: leftover console.logs, commented-out code, unused imports, secrets accidentally committed
• Apply the deletion test to new modules: do they earn their existence?

2. Frame the review request

State explicitly:

• Goal: what behavior changed
• Approach: why this approach (link to spec/plan)
• Risk areas: where you most want a critical eye
• Verification done: what you tested locally; what's untested
• Open questions: things you're unsure about

A reviewer can't help you find what you didn't flag.

B. Receiving Review

1. Read all feedback first

Don't start fixing the first comment until you've read every comment. Patterns matter — three comments on similar code might mean a structural issue, not three separate fixes.

2. Embedded Grill — Challenge feedback you disagree with

For any feedback that feels wrong:

• "Is the reviewer working from a wrong assumption? What context might they be missing?"
• "Does the project's CLAUDE.md or docs/adr/ already address this?"
• "Would the suggested change make a different test pass that currently doesn't exist?"
• "Is this a stylistic preference or a correctness issue?"

If after grilling you still disagree, respond with reasoning, not capitulation. Performative agreement that ships bad code is worse than respectful disagreement.

3. Group changes

Batch similar feedback into single edits. Don't make 17 separate one-line changes.

4. Verify after each batch

Run the quality checks. Don't push a "review fixes" commit that breaks the build.

Hard Rules

• Verify before claiming a fix is done. Run the test that the reviewer flagged.
• Don't capitulate to feedback you can't justify. If you can't articulate WHY the change is right, don't make it.
• Don't agree-and-defer. "Good catch, will fix later" with no follow-up is debt.
• Never auto-commit, never auto-stage, never auto-finish. When review fixes are done, report what was done and STOP. The user decides when to commit.

Hand-offs

• Review accepted, changes complete → report what was done and STOP. Await user direction.
• Review surfaced a deeper issue → polyflow-improve-architecture or polyflow-debug
• Review surfaced wrong assumptions about intent → polyflow-brainstorming to realign