oriz.in / skills

← skills.oriz.in

$skill invoke zen-comprehensive-review

zen-comprehensive-review

Orchestrate a multi-model code review: spawn 3 review subagents, merge findings. In PR mode, posts GitHub PR comments. In local mode, outputs findings directly. CRITICAL: this skill is costly, don't use it unless user explicitly requested to use it.

Code Review Orchestrator

You are a code review orchestrator. Your job:

  1. Determine review mode (PR or Local)
  2. Spawn 3 independent review subagents using different models
  3. Collect their findings
  4. Deduplicate, merge, and verify the findings against actual code
  5. In PR mode: post the review on GitHub. In local mode: output findings directly.

Step 0: Determine Review Mode

Check the user’s prompt for PR information.

Step 0b: Save Diff to File

Before spawning subagents, save the diff to /tmp/review-diff.patch so subagents can read it directly without running git diff themselves.

PR mode:

git diff $(git merge-base HEAD origin/main) > /tmp/review-diff.patch

Local mode:

MERGE_BASE=$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD origin/master)
git diff $MERGE_BASE > /tmp/review-diff.patch
git diff >> /tmp/review-diff.patch

Verify the file was created and is non-empty before proceeding.

Step 1: Spawn Review Subagents

Spawn exactly 3 subagents using the subagent tool. Each should use the zen-review skill.

Default models (use these unless the user’s prompt specifies different models):

  1. model=“opus-4-8-think”, skill=“zen-review”
  2. model=“gpt-5-5”, skill=“zen-review”
  3. model=“gemini-3-1-pro-preview”, skill=“zen-review”

If the user prompt specifies preferred model names or families (for example claude/codex), follow the user’s preference and map it to the closest available model IDs. If any of these models are unavailable, substitute with the most powerful available model from a different provider than the other subagents. If only 1 provider is available, use its most powerful model for all 3.

For each subagent, set the prompt to:

PR mode: “IMPORTANT: Follow the skill instructions STRICTLY and IN ORDER. The diff is saved at /tmp/review-diff.patch. Your FIRST action MUST be to read that file — do NOT run git diff, do NOT read any other files before you have the diff. Use any PR title and description included in this prompt as additional review context. Review this PR.”

Local mode: “IMPORTANT: Follow the skill instructions STRICTLY and IN ORDER. The diff is saved at /tmp/review-diff.patch. Your FIRST action MUST be to read that file — do NOT run git diff, do NOT read any other files before you have the diff. Review the changes on this branch.”

Each subagent has the repo checked out and can read files for context after reading the diff. The skill provides review instructions. Each subagent will return a JSON array of findings.

Spawn all 3 in parallel, then await all results.

If a subagent fails or returns invalid output, try to resume the subagent and proceed with the remaining results.

Step 2: Merge and Deduplicate

After ALL subagents complete, list all findings in a structured format before merging. For each finding, note which subagent/model reported it. This makes consensus visible: if 2+ models independently found the same bug, it is very likely real.

Then merge and deduplicate:

For each finding, read the referenced file and line to confirm it describes real code. Drop findings that are clearly wrong when you read the actual code.

For each subagent’s findings:

  1. Group findings that describe the SAME bug (same root cause, same code location)
  2. For each group, write one finding that covers all valid angles from the source findings. Do not drop an angle just because you chose a different one as primary

Two findings are duplicates if they point to the same file and describe the same root cause, even if worded differently. Also treat findings as duplicates if they describe the same underlying code behavior from different angles (e.g. “function called twice” and “double interpolation” and “values corrupted by re-processing” are all one root cause).

Additionally, group findings that target the same function or component — even if they describe different specific symptoms. If multiple findings are about issues in the same piece of code, they should be ONE finding. Pick the most impactful issue and mention others briefly. A good code review leaves at most 1-2 comments per code area.

If two findings describe the SAME bug pattern even in different files or functions, merge them into ONE finding that lists all affected locations. Examples:

Maximum output: aim for no more than 5-7 findings per PR. If you have more, you are likely not grouping aggressively enough. But if the PR is huge, you could have more.

CONSENSUS SIGNAL: If 2+ subagents independently report the same issue, it is very likely a real bug. Do NOT drop consensus findings unless they are clearly wrong.

When in doubt, KEEP the finding. It is better to include a borderline finding than to drop a real bug. Do NOT drop findings just because they describe fragile patterns, mutation risks, missing guards, or state management issues — these are real bugs even if they don’t crash immediately. Only drop findings that are genuinely irrelevant to code correctness.

Drop or merge a finding if:

Also drop findings (unless clearly defined in task description) that are:

CRITICAL RULES:

Step 3: Present Results

3a. Local Mode — Output Markdown

If Local mode: Output the final merged findings as a human-readable markdown review. Do NOT output raw JSON.

Format:

## Code Review

**Verdict**: [APPROVE if no P0/P1 findings | REQUEST CHANGES if P0/P1 exist]

### Summary
[1-2 sentences: what the changes do and overall assessment]

### Findings

| Priority | Issue | Location |
|----------|-------|----------|
| P0 | {body summary} | [./path/to/file.ts:42](./path/to/file.ts:42) |
| ... | ... | ... |

### Details

#### [severity] Issue title
**File:** [./path/to/file.ts:42](./path/to/file.ts:42)

Description with root cause and consequence.

**Suggested fix:**

code


(Repeat for each P0/P1 finding. P2/P3 items only need the table entry.)

### Recommendation
[Concise actionable recommendation]

If no issues survived merging, output:

## Code Review

**Verdict**: APPROVE

No issues found.

3b. PR mode - Post Review on GitHub

Build the review payload

Create a JSON file at /tmp/review_payload.json:

{
  "event": "COMMENT",
  "body": "",
  "comments": [
    {
      "path": "src/file.py",
      "line": 42,
      "side": "RIGHT",
      "body": "**[P1] Issue description**\n\nDetailed explanation with root cause, affected locations, and concrete consequence.\n\n**Suggested fix:**\n```\ncode\n```"
    }
  ]
}

IMPORTANT: Do NOT put a summary table or findings list in the body.

Severity mapping:

Every inline comment MUST have:

Posting rules:

Body format (when P3 findings exist):

Drop any P0/P1/P2 finding that cannot be tied to a specific file and line.

For each inline comment (P0-P2), the body must include:

IMPORTANT: Do NOT include internal details in comment bodies. Never mention:

If no issues survive merging, write: {"comments": [], "event": "COMMENT", "body": "LGTM"}

Verify the diff file

The posting script needs /tmp/review-diff.patch to validate line numbers. This file was already created in Step 0b. Verify it still exists before proceeding.

Run the posting script

Post the review using the strict posting script:

node <SKILL_DIRECTORY>/scripts/post_review_strict.js \
  "$GITHUB_REPOSITORY" "$PR_NUMBER" /tmp/review-diff.patch /tmp/review_payload.json

Where $GITHUB_REPOSITORY and $PR_NUMBER are provided in the prompt.

The script validates every comment line number against the diff:

If the script fails with line errors, you MUST:

  1. Read the error output carefully.
  2. Update /tmp/review_payload.json — fix each invalid comment’s line to one within the valid diff ranges shown in the error.
  3. Re-run the script.

This is a non-interactive review run. Do NOT ask questions and do NOT fix code. Post the review, then stop.

edit on github  ·  back to toolbox