review-pr

name	review-pr
description	Comprehensive PR review using the full agent team. Reviews for duplicates, suspicious changes, dependency changes, architecture violations, and spec compliance. Approves or rejects with consolidated findings.

Review PR — External & Internal PR Review Workflow

You are the orchestrator running a comprehensive review of a pull request using the full agent team. Follow these 6 steps in order. Do NOT skip steps. The orchestrator delegates all reviews — never post review comments directly. The orchestrator reads the diff independently to produce a behavior change summary.

When to use: Reviewing any PR — external contributions, Dependabot PRs, or re-reviewing after contributor pushes fixes. When NOT to use: PRs created by the /develop skill (those are reviewed inline during development).

Input

$ARGUMENTS contains the PR number (e.g., #581 or 581). If empty, ask the user to provide a PR number before proceeding.

Steps

1. PR Context Gathering

Fetch full PR metadata and diff:

gh pr view <pr-number> --json title,body,author,baseRefName,headRefName,files,url,labels,number,closingIssuesReferences

gh pr diff <pr-number>

Store the full diff — you will use it in Step 6 to produce an independent behavior change summary.

Classify affected areas by inspecting the changed files list:

• BACKEND — any files under server/ or shared/
• CLIENT — any files under client/
• TESTS — any files under e2e/ or files matching *.test.*
• DOCS — any files under docs/

Record all affected areas for use in Step 3 conditional agent launches.

Base branch enforcement — if the PR does not target beta, retarget it:

gh pr edit <pr-number> --base beta

2. Duplicate / Redundancy Check

Launch the product-owner agent to:

• Check if the feature or fix introduced by this PR is already implemented in the codebase
• Search GitHub Issues and the Projects board for overlapping or conflicting work
• Return one of:
  • UNIQUE — no overlap found, proceed
  • DUPLICATE — feature/fix already exists or is tracked by another issue. Stop the review. Post a comment on the PR explaining the duplication with references, then present the finding to the user
  • OVERLAPS — partial overlap with existing work. Flag the overlap and continue with the review

If DUPLICATE, skip all remaining steps.

3. Parallel Agent Reviews

Compute the applicable reviewers, then run them all in one review round. Each agent posts its own gh pr review on the PR (except dev-team-lead, see below).

Always include (every PR):

• product-architect — architecture compliance, API contract adherence, schema conventions, naming conventions, dependency policy
• security-engineer — conditional per the Security Review Trigger Rules in /develop step 8. Skip for frontend-only, test-only, docs-only, or CSS-only PRs.
• dev-team-lead — code quality, TypeScript strictness, ESM conventions, consistent-type-imports, test co-location. Participates as {agent: "dev-team-lead"} with focus "[MODE: review] — return VERDICT only; you have no GitHub write access in this mode". Does not post its own gh pr review — it returns VERDICT: APPROVED or VERDICT: CHANGES_REQUIRED as plain text to the orchestrator (handled in Step 4 below).

Conditional (based on affected areas from Step 1):

• CLIENT affected → ux-designer (token adherence, visual consistency, dark mode, responsive, accessibility) + frontend-developer (React patterns, hook conventions, component structure)
• BACKEND affected → backend-developer (Fastify patterns, Drizzle conventions, service layer structure, error handling)
• TESTS affected or test coverage gaps expected → qa-integration-tester (unit/integration test quality, coverage) + e2e-test-engineer (Playwright patterns, page objects, viewport coverage)
• DOCS affected → docs-writer (Docusaurus conventions, content accuracy, cross-references)

Before invoking the workflow, pre-fetch the diff once (gh pr diff <n> > /tmp/pr-<n>.diff) and derive per-reviewer file scopes from gh pr diff <n> --name-only (ux-designer/frontend-developer → client/src/ files; backend-developer → server/+shared/ files; security-engineer → trigger-rule matches; qa/e2e → test files; architect/dev-team-lead/product-owner → full list).

Then invoke the Workflow tool with {name: "pr-review", args: {pr: <n>, diffPath: "/tmp/pr-<n>.diff", reviewers: [{agent: "product-architect", files: [...]}, {agent: "dev-team-lead", ...}, ...]}} — one entry per applicable reviewer (same invocation as /develop step 8). Reviewers apply CLAUDE.md > Reviewer Verdict Policy (fix-or-block). If the Workflow tool is unavailable, fall back to launching the applicable reviewer agents in parallel with the Agent tool, passing the same diffPath and scopes.

Each agent receives:

• The PR number and URL
• The list of changed files relevant to their domain

Each agent except dev-team-lead receives instruction to post its own gh pr review with its findings. dev-team-lead instead returns its VERDICT text directly to the orchestrator — it never calls gh pr review.

4. Aggregate Reviews

After all agents complete, fetch all posted reviews:

gh api repos/steilerDev/cornerstone/pulls/<pr-number>/reviews

Parse each posted review to determine the agent's verdict (approve, request-changes, or comment) and summarize their findings. Separately, take the VERDICT text dev-team-lead returned directly (it does not post to GitHub) and map it into the same vocabulary: VERDICT: APPROVED → approve, VERDICT: CHANGES_REQUIRED → request-changes.

Determine overall verdict across both the posted reviews and dev-team-lead's mapped verdict:

• BLOCK: any agent (including dev-team-lead's mapped verdict) is effectively request-changes
• APPROVE: all posted reviews are approve/comment AND dev-team-lead returned VERDICT: APPROVED

5. Verdict Action

If BLOCK

Post a consolidated gh pr review --request-changes comment on the PR listing all blocking findings grouped by agent. Include specific file references and remediation guidance from each agent's review. Include dev-team-lead's findings (from its returned VERDICT text in Step 4) in this consolidated review, grouped alongside the other agents' findings.

Present the blocking findings to the user. Do NOT wait for CI.

If APPROVE

Post a consolidated gh pr review --approve comment on the PR summarizing the review outcome. Include dev-team-lead's findings (from its returned VERDICT text in Step 4) in this consolidated review, grouped alongside the other agents' findings.

Wait for CI: bash scripts/ci-wait.sh <pr-number> <beta|main> (pass main only when the PR targets main). The script handles the mergeability precheck, gate polling, timeout, and rate-limit backoff. If it reports a merge conflict, report the conflict to the user — do not attempt to resolve.

If CI fails, report the specific failures to the user. Do NOT merge.

6. User Report

Present to the user:

1. Agent Review Summary — the table from Step 4
2. Independent Behavior Change Summary — read the diff stored from Step 1 and describe what actually changed in user-visible terms, independent of the PR description or changelog. Flag any discrepancies between what the PR claims to do and what the code actually does.
3. CI Status — pass/fail for the required gate check(s) per CLAUDE.md: Quality Gates (required on both beta- and main-targeted PRs), plus E2E Gates (required only when the PR targets main). Docker, Docker PR Release, and Merge E2E Reports run but are not required gates — report them only if directly relevant, not as blocking checks. "Skipped" if review was blocked.
4. Overall Verdict — APPROVED or BLOCKED with specific next steps:
   • If approved: user can merge at their discretion (gh pr merge --squash <pr-number>; if the PR carries agent trailers worth preserving, use bash scripts/squash-merge.sh <pr-number> "<subject>" instead)
   • If blocked: list what the contributor needs to fix, suggest re-running /review-pr <number> after fixes are pushed

The orchestrator never merges. The user decides when to merge.