Run Review

run-review

Single entry point for every code-review intent. The skill does not silently pick a workflow — it routes by mode. On activation, pick the mode explicitly (or ask), then execute the per-mode procedure.

The four modes cover the only four review intents that exist in practice:

| Mode | Intent in one sentence | What used to live here | |---|---|---| | A — Do a review | Review someone's PR, branch, or diff for merge readiness. | the old review-pr / do-review skill | | B — Ask for review | Hand off your own branch as a reviewable PR (self-review body, optional gh pr create). | the old review-self / ask-review skill | | C — Evaluate received feedback | Triage human + bot comments, markdown audit docs, or earlier session feedback into accept / pushback / clarify / defer / dismiss. | the old review-feedback / evaluate-code-review skill | | D — Delegate to codex | Run codex review (or codex exec review) against the same target; surface findings back inside Claude. | new — wraps the codex CLI's native review command |

This skill replaces those three older skills and folds codex review in as a peer mode, so the user never has to guess which review skill to pick.

When to use this skill

Trigger phrases (any one is sufficient):

• "review PR #N", "review github.com/owner/repo/pull/N", "walk this diff", "is this safe to merge?" → Mode A
• "open a PR for this", "write me a self-review", "this is ready for review", "hand this off" → Mode B
• "address the review comments on PR #N", "the bots reviewed my PR", "go back over the reviewer's notes", "read review.md and give me an action plan" → Mode C
• "run codex review on this", "have codex review the diff", "codex review --uncommitted", "second opinion from codex" → Mode D

Do not use this skill for:

• per-branch codex review fix loops over a list of branches → multi-branch codex review orchestration
• repo-cleanup of dirty trees across multiple worktrees with no review handoff yet → run-repo-cleanup
• chasing a runtime bug with no diff to judge → debug-runtime
• generic codex-CLI orchestration without a review intent → parallel codex exec orchestration or parallel codex exec orchestration

Mode selection (load-bearing — do not skip)

On every activation, before any tool call beyond reading state:

1. Read the user's literal phrasing against the trigger table above.
2. Apply the inference rules (next subsection). If a single mode wins with high confidence, state the mode in one line and proceed.
3. If two or more modes are plausible, ASK. Default to asking when in doubt — a wrong mode wastes a lot of subagent compute. Use AskUserQuestion when available; otherwise emit the inline numbered prompt below.

Inference rules

Apply in order; the first matching rule wins. Each rule lists the literal cue and the mode it routes to.

| # | Cue in the user's request | Mode | |---|---|---| | 1 | The phrase codex review, codex exec review, have codex review, or any direct mention of running the codex CLI to review code. | D | | 2 | Words open a PR / hand off / ready for review / self-review / write the review body / ship this branch applied to the user's own work, AND no third-party review comments are named. | B | | 3 | Words evaluate / triage / address / respond to / answer / sort out applied to feedback already in hand — PR comments, named bots (Copilot, CodeRabbit, Greptile, Devin, Bito, Codex), or a markdown file like review.md / audit.md / feedback.md. | C | | 4 | A PR number, URL, branch comparison, or gh pr view target named by the user with words review / look at / merge-readiness / walk this diff / sanity-check, and no mention of codex CLI. | A | | 5 | None of the above OR multiple rules fire at the same confidence. | ASK |

When confidence is borderline (e.g., the user names a PR but also says "have codex take a look") — that is rule 1 first; codex CLI wins. When the user says "open a PR and have codex review it" — that is two modes in sequence: B (open the PR) then D (codex review against the new branch). Run them in order and say so out loud before starting.

How to ask when ambiguous

If the user's phrasing does not uniquely select a mode, surface the four choices verbatim and stop. Use the AskUserQuestion tool when available with one question and these four options. Otherwise emit this block in chat and wait:

I can run this in one of four review modes. Which do you want?

  A) Do a review — I review your PR / branch / diff for merge readiness.
  B) Ask for review — I clean up your branch and open a PR with a self-review body.
  C) Evaluate received feedback — I triage comments / bot output / a review doc into an action plan.
  D) Delegate to codex — I run `codex review` against the diff and surface its findings.

Reply with A, B, C, or D (or describe the work in one line).

Never hide a mode to "narrow" the choice. The user must always see all four. Multi-mode requests are fine — they execute in sequence.

Once the mode is locked

State the chosen mode in one line before starting. Do not swap modes mid-workflow without re-asking. If, while executing, you discover the user actually wanted a different mode, stop, name the mismatch, and re-route.

Mode A — Do a review (review someone's PR / branch / diff)

Trigger phrases

"review PR #123", "review github.com/owner/repo/pull/N", "is this safe to merge?", "walk this diff", "review main...feature-branch", "review my working tree", "the PR already has CodeRabbit comments — what's left?", "this PR has 40 files; tell me what to look at first".

Required inputs

Exactly one comparison target. Name it in one line before reading code:

• owner/repo#N for GitHub PR mode
• ... for branch diff mode (e.g. origin/main...HEAD)
• HEAD + staged + unstaged for working-tree mode

If the target cannot be named in one line, stop and ask. Do not invent a diff target.

Procedure (8 phases, owned by Mode A)

1. Triage the request — full vs targeted, draft vs ready, security-only vs general. Inline; no reference.
2. Gather context before code — references/mode-a-do-review/workflow/review-workflow.md (Phase 1). Tooling: scripts/parse-pr.sh (see scripts/parse-pr.md), references/mode-a-do-review/workflow/gh-cli-reference.md.
3. Scope and cluster files — references/mode-a-do-review/analysis/file-clustering.md. Tooling: scripts/cluster-files.sh (see scripts/cluster-files.md).
4. Read existing review state — references/mode-a-do-review/workflow/comment-correlation.md, references/mode-a-do-review/workflow/automation.md. Treat Copilot, CodeRabbit, Greptile, Devin, Bito, CodeQL, Snyk, etc. as prior review — dedupe, do not repeat.
5. Validate goals — references/mode-a-do-review/workflow/review-workflow.md (Phase 4). A PR that passes every quality check but misses its stated outcome is a failed PR.
6. Review by cluster — apply dimensions in order: security → correctness → data integrity → API contract → performance → tests → maintainability. Detail: references/mode-a-do-review/dimensions/review-dimensions.md, references/mode-a-do-review/dimensions/security-review.md, references/mode-a-do-review/dimensions/performance-review.md, references/mode-a-do-review/dimensions/bug-patterns.md, references/mode-a-do-review/dimensions/language-specific.md. Diff reading help: references/mode-a-do-review/analysis/diff-analysis.md.
7. Cross-cutting sweep — references/mode-a-do-review/analysis/cross-cutting.md. Large PR strategy: references/mode-a-do-review/analysis/large-pr-strategy.md.
8. Calibrate, synthesize, output — references/mode-a-do-review/output/output-templates.md, references/mode-a-do-review/output/communication.md, references/mode-a-do-review/output/anti-patterns.md. Severity calibration: references/mode-a-do-review/dimensions/severity-guide.md.

Subagent dispatch — when to fan out

Mode A is single-agent by default. Dispatch subagents only when ALL of:

• changed files ≥ 15 OR changed lines > 500
• cluster map (Phase 3) shows ≥ 2 high-risk clusters that can be reviewed independently
• the user has not asked for a quick / shallow review

If those conditions hold, dispatch one subagent per cluster. Each subagent receives: cluster file list, base/head refs, the dimensions checklist at references/mode-a-do-review/dimensions/review-dimensions.md, and the actionability gate from Phase 6. Subagents return findings only — the parent agent owns calibration, dedup, and verdict.

For PR `. Capture: dirty? on default branch? unpushed? PR already exists?

1. Handle dirty tree first — commit before opening the PR, never after. Diff-walk commits, group by domain, one conventional commit per concern. No git commit -am, no blind git add -A. If on default branch, create a branch first (git switch -c /-). Detail: references/mode-b-ask-review/handoff-mechanics.md. RED-baseline excuses to refuse: references/mode-b-ask-review/rationalizations.md.
2. Classify the diff's domain — match the changed paths against one of seven domains. Read the one that matches before drafting:

• server / API / SQL / auth / infra → references/mode-b-ask-review/domains/backend.md
• client-side TS / JS / React / Vue / Svelte (outside server/) → references/mode-b-ask-review/domains/frontend-ts-js.md
• @modelcontextprotocol/sdk imports, Zod tool schemas, SKILL.md authoring → references/mode-b-ask-review/domains/mcp-server.md
• CSS / Tailwind / design tokens / a11y / layout → references/mode-b-ask-review/domains/ui-engineering.md
• bin/, scripts/*.sh, argparse / commander, flag parsing, exit codes → references/mode-b-ask-review/domains/cli-tool.md
• prose *.md under content/, posts/, docs/, README bodies → references/mode-b-ask-review/domains/content-markdown.md
• anything else or a clear mix that does not split cleanly → references/mode-b-ask-review/domains/generic.md

1. Draft the body — follow references/mode-b-ask-review/review-text-template.md. Under 50,000 chars; explain every change; surface ≥ 2 weaknesses the author already knows about; ask ≥ 1 explicit reviewer question.
2. Ship it — gh pr create --repo / --base --head --title "(): " --body-file /tmp/pr-body.md, then verify with gh pr view --repo / --json url,baseRefName,headRefName. URL must point to the intended repo; base must be the intended target.

Subagent dispatch — when to fan out

Dispatch when the diff touches 2+ domains AND each domain has ≥ 5% of the changed lines. One subagent per domain cluster. Each subagent receives: BASE_SHA + HEAD_SHA, paths restricted to its cluster, the matching domain reference, and the prompt template at references/mode-b-ask-review/subagent-dispatch.md. Each returns per-domain change summary, weaknesses, 1-3 reviewer questions.

Combine outputs into one coherent body — one section per domain under an ## Areas heading, plus an overall summary. Single-domain diffs skip this step.

Output shape

PR handoff: PR URL plus the verification block from gh pr view. Markdown mode: the body inline or written to the user-named path. Body must include weaknesses (≥ 2) and reviewer questions (≥ 1).

Hand-off contract

After Mode B: branch is pushed, PR is open (PR mode) or markdown is delivered (doc mode). git status --short is empty on the author's branch. The reviewer now owns the next move. Do not start running fixes from your own self-review weaknesses — those are signals to the reviewer.

Mode C — Evaluate received feedback

Trigger phrases

"address the review comments on PR #42", "what do the bots say on my PR", "Copilot and CodeRabbit disagree — sort it out", "merge what the three reviewers said", "go back and check the reviewer's notes from earlier", "read review.md and give me an action plan", "the reviewer's notes are in audit.md", "reply in the PR threads with my answers".

Required inputs

Feedback in one of three shapes:

| Input mode | Detection | Source | |---|---|---| | PR mode | user names a PR (number, URL) and review comments | scripts/parse-pr-comments.sh --repo --pr --out (see scripts/parse-pr-comments.md) | | Session-audit mode | user references review notes earlier in this conversation | prior messages | | Markdown-doc mode | user names a file like review.md, audit.md, feedback.md | the file on disk |

If genuinely ambiguous: scan prior messages, then gh pr view on the current branch, then look for review*.md / audit*.md / feedback*.md in the working dir. Report what was found before proceeding.

Procedure

1. Identify the input mode and surface the feedback — extract every item as a flat list with verbatim text, source, location, code-range metadata, severity hint. For PR mode, run scripts/parse-pr-comments.sh to fetch all three GitHub feedback channels (top-level reviews, inline review comments, PR-discussion comments).
2. Reconstruct ground truth — what change set should the reviewer have been looking at? Fallback chain at references/mode-c-evaluate-feedback/understand-changes.md: branch commits → tool-trail (Edit/Write calls in the session) → bash trail → uncertain. Stop and name uncertainty rather than guessing.
3. Dispatch an Explore subagent — ALWAYS. Even single-item reviews. Self-contained prompt — no "as we discussed earlier", no session references. Template: references/mode-c-evaluate-feedback/subagent-dispatch.md. Subagent returns per-item {verdict, evidence: file:line + reasoning, severity}.
4. Consolidate multi-source feedback — if 2+ reviewers, line-range cluster (same file + overlapping range, ±5 lines) and merge duplicates. Surface conflicts explicitly — never silently pick one. Detail: references/mode-c-evaluate-feedback/multi-agent-consolidation.md. Tooling: scripts/cluster-feedback.py --input normalized.jsonl --output clusters.json (see scripts/cluster-feedback.md).
5. Evaluate each item — combine the subagent's verdict with parent verification. Six-check lens at references/mode-c-evaluate-feedback/verification.md. Each item gets one verdict:

| Verdict | Meaning | |---|---| | ACCEPT | feedback is correct and worth acting on | | PUSHBACK | feedback is wrong; respond with technical reasoning | | CLARIFY | feedback is unclear or evidence is missing; ask | | DEFER | correct but out of scope for this PR; log as follow-up | | DISMISS | noise, unambiguously wrong, or reviewer lacks context |

1. Produce the action plan — format depends on input mode. See references/mode-c-evaluate-feedback/action-plan-output.md. PR mode: reply in threads via gh api repos/{o}/{r}/pulls/{pr}/comments/{id}/replies. Session-audit mode: markdown action plan inline. Markdown-doc mode: write -action-plan.md next to the source.
2. Implement (only if authorized) — order: blocking → simple → complex. One item at a time, test each before the next. After each item, reply in the thread (PR mode) or update the plan (markdown mode) with Fixed. . — no gratitude, no praise, no apology.

Voice discipline (load-bearing)

No performative agreement. No gratitude. No praise. No apology. No agreement-before-verification. The diff is the acknowledgment. Phrase-level rules at references/mode-c-evaluate-feedback/voice.md. Pressure-scenario excuses at references/mode-c-evaluate-feedback/rationalizations.md. GH thread mechanics at references/mode-c-evaluate-feedback/gh-review-workflow.md.

Subagent dispatch — when to fan out

The single Explore subagent in Step 3 is mandatory even for one-item reviews — bias control, not parallelism. Fan out further when ≥ 30 distinct feedback items survive deduplication. Group items by file or by cluster (

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yigitkonur
• Source: yigitkonur/skills-by-yigitkonur
• License: MIT

Install and usage instructions live in the source repository linked above.