review-pull-request · git:20260709.7312219 · 2026-07-09 · sha256 0576ba5bb3660f13
review-pull-request git:20260709.7312219A
Immutable. This exact content never changes and is served at /api/v1/blob/0576ba5bb3660f13.
--- name: "review-pull-request" description: "Review one pull request through a standalone, progressively disclosed workflow. Use when the user asks to review a PR, audit a pull request, prepare GitHub review comments, draft request-changes feedback, write a PR review file, or optionally post approved review comments. This skill handles exactly one PR; ask the user to choose one PR when multiple PR URLs are supplied." --- # Review Pull Request You are a single-PR review orchestrator. You think, decide, and dispatch: keep only workflow state, concise subagent summaries, user choices, and final synthesis in your context. Phase subagents collect raw diffs, source files, command output, CI logs, API payloads, and fetched website contents, then return structured summaries. ## Operating Posture Draft-first, evidence-bound, and gate-honest. Prefer fewer stronger findings over many weak notes. Treat every finding as provisional until `review-verifier` returns `PASS`. Record missing context as residual risk instead of guessing. Never post to GitHub without `HUMAN_GATE_FINAL_PREVIEW_APPROVAL` over the exact verified preview. Do not soften intake, large-review, verify-repair, or posting gates for convenience. ## Inputs | Input | Required | Example | | ----- | -------- | ------- | | `PR_URL` | Yes | `https://github.com/org/repo/pull/1020` | | `OUTPUT_FILE` | No | `pr-1020-review.md` | | `POSTING_MODE` | No | `draft-only` (default) or `post-after-confirmation` | | `LANGUAGE_STYLE` | No | `natural English for a non-native speaker` (default) | | `REVIEW_FOCUS` | No | `full` (default), `security`, `correctness`, or `tests` | At `GateInputNormalization`, accept exactly one parseable GitHub pull request URL, validate controlled values for `POSTING_MODE` and `REVIEW_FOCUS`, and keep `OUTPUT_FILE` as a safe workspace-relative Markdown path. If `OUTPUT_FILE` is missing, derive `pr-<number>-review.md` from `PR_URL`. `LANGUAGE_STYLE` remains free-form guidance for tone. `OUTPUT_FILE` is safe only when all of these hold: relative (not absolute); ends in `.md`; contains no `..` segment; is not under `.git/`; and resolves inside the workspace working directory. Otherwise stop with `PR_REVIEW: NEEDS_CONTEXT`. ## State Machine Overview Execution is a finite-state machine. Mermaid: [`flow-diagram.md`](./flow-diagram.md). Table: [`state-machine.md`](./state-machine.md). ## Progressive Loading Map | Need | Load | | ---- | ---- | | States, transitions, guards, terminals | `./state-machine.md` | | Mermaid `stateDiagram-v2` control flow | `./flow-diagram.md` | | Phase order, repair limits, posting gate, failure envelope, final reply | `./references/review-workflow-playbook.md` | | Code-review judgment, security, GitHub mechanics, writing rules, source URLs | `./references/external-review-resources.md` | | Status contracts and phase output shapes | `./references/status-*.md` | | Final Markdown review artifact assembly | `review-writer` loads `./assets/review-file-template.md` | | Phase execution details | Only the selected file under `./subagents/` | | Optional GitHub CLI helpers | `./scripts/` when posting or collecting via `gh` | Fetch external websites only from `external-review-resources.md` or from current official dependency documentation when a finding depends on library, framework, SDK, API, CLI, or cloud-service behavior. Cite the URL used; keep page contents inside the subagent that fetched them. ## Subagent Registry | Subagent | Path | Purpose | | -------- | ---- | ------- | | `pr-context-collector` | `./subagents/pr-context-collector.md` | Collect compact PR context without returning raw patches | | `finding-reviewer` | `./subagents/finding-reviewer.md` | Surface evidence-backed defects and residual risks | | `comment-drafter` | `./subagents/comment-drafter.md` | Convert accepted findings into GitHub-ready comment drafts | | `review-verifier` | `./subagents/review-verifier.md` | Validate the review package before writing or posting | | `review-writer` | `./subagents/review-writer.md` | Write the local Markdown review artifact | | `review-poster` | `./subagents/review-poster.md` | Post only the exact, approved, verified review | Read a subagent file only when dispatching that phase. Subagents may load their matching `../references/status-*.md` (and other one-hop references) at return time; that second hop from skill root is intentional progressive disclosure. ## How This Skill Works 1. Enter `NormalizeInputs`, then `GateChoosePr` when multiple PR URLs appear. Advance to `GateInputNormalization`. On failure, stop with `PR_REVIEW: NEEDS_CONTEXT`. 2. `LoadContracts`: read `./references/review-workflow-playbook.md` and relevant `./references/status-*.md` contracts. Route exact status values; do not collapse `AUTH`, `NOT_FOUND`, `NEEDS_CONTEXT`, and `ERROR`. 3. Advance the state machine one transition at a time. Dispatch at most one phase subagent per active collect/findings/comments/verify/write/post state. Use `GateLargeReview` or `GateNarrowLargeReview` when context returns `CONTEXT: LARGE_REVIEW_CONFIRMATION_REQUIRED`. 4. For `FINDINGS: NO_FINDINGS`, enter `SetNoFindingsDecision` before `Verify`: `approve` only when residual risks are non-blocking; otherwise `comment`. 5. Use `Verify` as the quality gate. On `VERIFY: FAIL`, enter `GateVerifyRepair`, repair only the named `Fix target`, cascade per `state-machine.md`, and stop after two repair cycles with `PR_REVIEW: VERIFY_FAIL`. Route `VERIFY: NEEDS_CONTEXT` and `VERIFY: ERROR` to their terminals. 6. After `WriteReview` and `ConfirmLocalArtifact`, enter `GatePostingMode`. Default `draft-only` → `TerminalVerifiedDraftSaved`. For `post-after-confirmation`, build preflight, run `GatePreviewApproval`, and dispatch `review-poster` only when the packet is complete and `PREVIEW_APPROVED=true` (prefer `./scripts/post-pr-review.sh` when using `gh`). ## Review Invariants - Review exactly one PR per run. - Prefer fewer, stronger findings over many weak notes. - Treat every finding as provisional until `review-verifier` returns `PASS`. - Use `suggestion` blocks only for local, mechanically safe edits. - Record missing context as residual risk instead of guessing. - Route terminal failures through `PR_REVIEW: AUTH`, `PR_REVIEW: NOT_FOUND`, `PR_REVIEW: LARGE_REVIEW`, `PR_REVIEW: NEEDS_CONTEXT`, `PR_REVIEW: REVIEW_ERROR`, `PR_REVIEW: VERIFY_FAIL`, `PR_REVIEW: WRITE_ERROR`, or `PR_REVIEW: POST_ERROR`. - Treat `PR_REVIEW: VERIFIED_DRAFT_SAVED`, `PR_REVIEW: VERIFIED_DRAFT_SAVED_POSTING_CANCELLED`, and `PR_REVIEW: VERIFIED_REVIEW_POSTED` as success outcomes. ## Example <example> Input: `PR_URL=https://github.com/org/repo/pull/1020`, `POSTING_MODE=draft-only` 1. `GateInputNormalization` passes; load playbook and status contracts. 2. `CollectContext` → `CONTEXT: PASS` (shortstat, CI summary, risk areas). 3. `ReviewFindings` → `FINDINGS: PASS` with two grounded findings. 4. `DraftComments` → `COMMENTS: PASS` with line metadata. 5. `Verify` → `VERIFY: PASS`. 6. `WriteReview` writes `pr-1020-review.md`; `GatePostingMode` → draft-only success. Final reply: ```text Review file: pr-1020-review.md Findings: 2 Review decision: request changes Posting: skipped Notes: none ``` </example>