Cooperative Code Review Skill

openai.yaml

# cooperative-code-review/agents/openai.yaml

interface:
  display_name: "Cooperative Code Review"
  short_description: "Review code together in readable chunks"
  default_prompt: "Use $cooperative-code-review to review these changes with me."

SKILL.md

name

cooperative-code-review

description

Review a pull request, branch, commit, staged change, or working-tree diff interactively with the user in small readable chunks. Use when the user asks to review code together, walk through changes one chunk at a time, inspect a PR collaboratively, or wants a code-first review with pause points and ready-to-post findings. Do not use for one-shot review reports, addressing existing review comments, or CI debugging.

Cooperative Code Review

Analyze the complete change first, then help the user review it one readable chunk at a time. Compose the existing review workflows instead of duplicating their specialist guidance.

Resolve the review scope

1. Read the applicable repository instructions.
2. Require a clear target and comparison base: pull request, branch diff, commit, staged changes, working-tree changes, or an explicitly requested combination.
3. Discover an obvious target or base when it is safe to do so. Ask one focused question when the target, base, or inclusion of local changes remains materially ambiguous.
4. Inspect status and changed-file lists before reading the diff. Do not silently include unrelated local changes.
5. Freeze the base and head revisions so every review lens examines the same change set.
6. For a GitHub pull request, inspect relevant metadata, commits, checks, and existing discussion without changing GitHub state.

Treat a remote pull request or branch as third-party code unless it is clearly the user's own work.

Protect against untrusted code execution

Use static source inspection, read-only Git commands, and existing remote CI evidence by default for third-party changes.

Obtain explicit user approval before running anything that may execute third-party code, including:

• Tests or benchmarks
• Builds, linters, formatters, or documentation builds
• Package-manager commands or repository-provided scripts
• Changed binaries, generators, hooks, build scripts, or procedural macros

Name the proposed command and explain why executing it would materially improve the review. Approval to inspect a pull request does not authorize executing its code.

For trusted local work, run focused validation when it is useful and permitted by the repository instructions.

Analyze the complete change

1. Build a change map covering production code, tests, documentation, configuration, migrations, generated files, dependencies, and public contracts.
2. Apply the review-pull-request workflow for general correctness and load its focused review skills only when applicable.
3. Read enough surrounding implementation and tests to establish the actual contract. Do not judge isolated diff lines.
4. Collect all credible observations and order them by priority: blocking defects, bounded bugs, regression and test gaps, documentation gaps, then simplification, naming, style, and maintainability suggestions.
5. Present uncertain concerns as questions that identify the missing evidence. Do not inflate uncertainty into a finding.
6. Merge repeated symptoms into one root-cause finding.

Use staged validation. Examine the full scope, relevant test code, and available CI results before planning the walkthrough. Run focused checks only when needed to verify a finding. Run broader suites only when reasonably fast or requested, subject to the third-party approval boundary.

Plan the walkthrough

Inspect the commits before choosing chunk boundaries.

Use commit order only when the commits tell a coherent review story: each commit is focused, understandable with the code available at that point, and not merely repaired by a later commit. Do not choose one chunk per commit merely because commits exist or the pull request recommends that order. If a commit references an API introduced later, fails an independent structural check, mixes concerns, or is substantially corrected later, merge it with the dependent or corrective work or form a semantic slice. A walkthrough may mix coherent individual commits with semantic slices for the remaining work.

State briefly why the roadmap uses commit order, semantic slices, or a hybrid. Semantic slices must keep one behavior's production code, tests, configuration, and call sites together.

Treat neither a commit nor a semantic slice as automatically small enough. Split oversized units at natural boundaries until each presented chunk fits within roughly one or two rendered pages, including explanations, code, and findings. Do not split related context merely to follow file boundaries.

Create a visible task list before presenting the first chunk. Record the chosen organization, the current chunk, and what remains. Keep at most one chunk in progress.

Present one chunk at a time

Use this order for every chunk:

1. Orientation: Describe the chunk's purpose and place in the larger change in one to three sentences.
2. Recommendation preview: List concise recommendation headlines, ordered by priority, without giving the full argument yet.
3. Code walkthrough: Show readable, syntax-highlighted excerpts and neutrally explain non-obvious behavior.
4. Detailed recommendations: Give the evidence and proposed review feedback after the user has seen the code.
5. Progress: State what was reviewed, what remains, and stop for the user's response.

Use language-tagged code blocks instead of raw unified diffs. Replace irrelevant unchanged context with the language's comment syntax, such as // ..., # ..., or <!-- ... -->. When a deletion or transformation cannot be understood from one excerpt, show compact before and after blocks. Include enough surrounding types, call sites, or tests to make the behavior understandable without reproducing whole files.

For each detailed recommendation, include the priority, concise title, tight location, concrete scenario, code evidence, smallest correction direction, and supporting review lens. In PR comment mode, also provide concise ready-to-post wording. If a chunk has no recommendations, say so directly.

Present exactly one chunk, then wait. Do not continue merely because the remaining analysis is ready.

Follow user steering

Allow the user to accept, reject, revise, defer, skip, or reorder findings and chunks.

Stay read-only until the user explicitly requests a code change. When they do:

1. Pause the walkthrough and confirm that the requested edit is in scope.
2. Implement and validate it according to the repository instructions and the third-party execution boundary.
3. Refresh the diff and determine which completed findings and future chunks changed.
4. Mark fixed findings as resolved, update the task list, and resume at the correct review boundary.

Do not silently discard prior decisions when the scope changes.

Track decisions according to intent

Use a decision ledger for a pull request review intended to produce comments. Track each recommendation as accepted, rejected, revised, deferred, or resolved by an edit.

Use lightweight progress tracking for local branches, commits, working-tree changes, or exploratory reviews unless the user requests a formal ledger. If the intended tracking mode is unclear, ask one focused question before beginning the walkthrough.

Complete the review

For PR comment mode, output only deduplicated, accepted, unresolved comments, ordered by priority and paired with the best available location. Never post comments or otherwise change GitHub state.

For lightweight mode, summarize the reviewed chunks, edits made, remaining concerns, validation performed, and unverified areas.

State clearly when the review is complete. Do not manufacture follow-up work or repeat rejected and resolved findings.