tobihagemann/peer-review

Peer Review

Independent peer review via Claude. Translates a natural-language review request into a Claude-specific prompt so invocations stay implementation-agnostic.

Step 1: Determine Review Request

Extract from the current context:

• Material — code diff, files, plan, spec, shells, feedback, or other artifact to review
• Review dimensions — correctness, security, API usage, consistency, simplicity, coverage, plan readiness, spec quality, feedback interpretation, or explicit user criteria
• Criteria — reference file paths Claude should read directly, inline criteria text, or the material's own domain conventions
• Output format — findings schema, verdict labels, priority scale, and any required metadata fields

If no reviewable material is available, stop and state that material is required.

Step 2: Build the Claude Prompt

Assemble a prompt for Claude:

• State that Claude is acting as an independent peer reviewer for Codex.
• Identify the exact material and scope. Pass text you did not author as file paths and diff commands rather than pasted content.
• Instruct Claude to read referenced criteria files directly.
• Bound Claude's reads to the material under review, the sources needed to verify claims about it, and the criteria identified in Step 1. Exclude documents unrelated to those three.
• Preserve independent dimensions. If multiple dimensions are requested and Codex sub-agent fan-out is unavailable, ask Claude to review each dimension in a separately labeled section. When the request instead asks explicitly for a single-pass review covering all dimensions, keep it to one pass with each dimension in its own labeled section rather than fanning out.
• Require the exact output format expected by the calling skill.
• Require evidence for every actionable finding.
• Tell Claude not to modify files.
• Tell Claude to perform the review itself rather than delegating to another peer review skill or back to Codex. The prompt has already crossed the tool boundary; further forwarding would loop.

Step 3: Run $claude-print Skill

Run $claude-print in read-only mode with the assembled prompt.

Step 4: Validate Output

Compare Claude's output against the reviewed material and the dimensions and structure requested in Step 2, then classify it into one of three branches:

• Claude returned the requested findings — output them verbatim.
• Incomplete output (any reason — partial fan-out with missing dimensions, mid-run truncation, sections cut off, sub-agent failure, single-dimension review that ends mid-finding, etc.) — output what came back verbatim, name what is missing relative to Step 2's request, then append: "Action required: Peer review returned partial output. Use request_user_input to ask the user whether to retry peer review now (transient Claude errors like usage limits often clear within minutes) or proceed with the partial findings. State what is missing so the user can decide."
• No output / Claude failed — Claude returned nothing, errored, hit a usage limit, or returned off-topic output that addresses code, files, or topics outside the reviewed material instead of the requested findings. Do not emit off-topic content as findings. Output a single notice stating the cause, then append: "Action required: Peer review failed. Use request_user_input to ask the user whether to retry peer review now (transient Claude errors like usage limits often clear within minutes) or proceed without peer review."

Do not synthesize peer findings locally to fill a gap. Peer review's value is independence; locally written findings labeled "peer" mislead the consumer.

Then call update_plan to mark this step completed and continue with the next step of the active workflow.

Rules

• $peer-review is the stable abstraction. Pipeline skills should not call $claude-print directly unless they need raw Claude print-mode behavior.
• Do not apply Claude findings directly. Evaluation and application belong to downstream skills.