peer-review

name	peer-review
description	peer-review a plan, design, or implementation, find the one critical risk, list other gaps, propose a fix for the critical risk, and update the plan. Triggers: peer review a plan, review an implementation, assess a design, check a proposal for gaps.

Peer Review

Step 1: Gather context

Read everything relevant before analyzing:

• Requirements: the spec, ticket, or PR description defining what must be built
• Plan: the implementation plan, design doc, or proposed changes
• Code: the actual implementation, diff, or relevant source
• Contracts: OpenAPI/protobuf/API docs; package.json/requirements.txt/Cargo.toml for related libs
• History: related bugs, incidents, or post-mortems
• Tests: existing test files for current coverage

Step 2: Analyze against requirements

Compare the plan to the requirements. Check completeness, edge cases (boundaries, empty inputs, max values, races), error states and rollback, failure modes (a downstream service down/slow/returning garbage), hidden ordering or version conflicts, performance (N+1, unbounded loops, leaks), security (input validation, auth, secrets, data integrity), and test adequacy.

Focus on what is most likely to cause failure, not every theoretical issue.

Step 3: Write the review

Exactly four sections. Maximum clarity, minimum words.

Critical Risk

One paragraph naming the single thing most likely to cause failure, why it is dangerous and under what conditions it breaks. Pick the highest-impact, most probable one; do not list several.

Other Gaps

Bulleted secondary issues, one line each, formatted - <issue> → <impact>. Only real, material issues, no nitpicks or theoretical concerns.

Fix

Numbered, concrete, actionable steps that address the critical risk only.

Verdict

One sentence, exactly one of: "Ship it." / "Fix the critical risk first, then ship." / "Needs rework." No explanation.

Step 4: Update the plan

Apply the Fix steps to the plan files directly, the smallest change that mitigates the critical risk. Report which files changed and the fix applied.

Style

• Concrete language only. No vague warnings ("be careful with X").
• Back every claim with evidence from what you read.