cy-impl-peer-review

Implementation Peer Review

Claude Opus pressure-tests an implementation diff via compozy exec. This skill runs that pressure-test only when the user explicitly asks for a review round after an implementation pass. It is decoupled from any PRD/task tracking system — the scope is the diff itself plus any optional context files the user names. The skill never auto-runs, auto-incorporates findings, auto-commits, or auto-loops additional rounds.

User Decisions

When this skill instructs the agent to ask whether to incorporate findings or run another round, it MUST use the runtime's dedicated interactive question tool — the tool or function that presents a question to the user and pauses execution until the user responds.

If the runtime does not provide such a tool, present the question as the complete assistant message and stop generating. Do not answer the question on the user's behalf.

Optional Inputs

All inputs are optional. Defaults make the common path cy-impl-peer-review with no arguments.

• --files <path1,path2,...> — scope the review to explicit paths instead of the full branch diff.
• --context <path1,path2,...> — additional context files to feed Opus (e.g., a spec, ADR, design doc, RFC, README). The skill never assumes any of these exist.
• --base <git-ref> — base ref for the diff. Defaults to main. Use --base HEAD~N or --staged for narrower scopes.
• --out <dir> — output directory for round artifacts. Defaults to .peer-reviews/<UTC-timestamp>/ at repo root.

Procedures

Step 1: Validate Input and Compute Scope

1. Confirm the user has just completed (or paused) the implementation pass and explicitly asked to review the current state. Do not run review rounds during active editing.
2. Resolve the diff scope:
   • If --files is provided, verify each path exists and limit the diff to those paths.
   • If --staged is provided as the base, use git diff --staged.
   • Otherwise run git diff <base>...HEAD --name-only (default <base> is main) to compute the changed file set. If the diff is empty, abort and tell the user there is nothing to review.
3. Resolve the artifact directory:
   • Use --out if provided.
   • Otherwise default to .peer-reviews/<UTC-timestamp-YYYYMMDDTHHMMSSZ>/ at the repository root.
   • Create the directory if it does not exist.
4. Read .agents/skills/cy-impl-peer-review/references/readiness-checks.md and verify every readiness marker passes (build/tests green, no committed .tmp/ or ai-docs/, diff is non-empty, no obvious WIP markers in changed files, codegen co-ship if contracts touched, migration co-ship if schema touched, reviewable size). If any marker fails, report the failed markers and abort — Opus review on a broken or incomplete change wastes credit and produces noise.
5. Determine the next review round number by listing existing impl-review-result-round*.json files in the artifact directory. Start at round1 when none exist.