github-review-pr
Reviews a GitHub pull request by URL or owner/repo#number and writes a findings report with a verdict. Use when the user says "review this PR", pastes a PR link or asks if a change is safe to merge. N
SKILL.mdplugins/mz-dev-git/skills/github-review-pr/SKILL.md
GitHubReview PR
Overview
Dispatch the github-pr-reviewer agent to perform a thorough review of a GitHub pull request in a temporary PR worktree that the agent creates and removes. Produces a report under .mz/reviews/ with severity-labeled findings and a verdict.
When to Use
Reviewing a GitHub pull request, given by URL or owner/repo#number, and writing a findings report with a verdict.
When NOT to use
- The changes live on a local branch, not a GitHub PR — use
review-branch. - The user wants to triage many PRs at once — use
github-scan-prs. - The PR reference is ambiguous or missing — ask for a URL or
owner/repo#number.
Arguments
$ARGUMENTS should be a GitHub PR reference:
- Full URL:
https://github.com/owner/repo/pull/123 - Short form:
owner/repo#123
If no argument is provided, ask the user for a PR URL.
Constants
- PROJECT_ROOT: resolved once in setup with
echo "${MZ_MEMORY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; expand<PROJECT_ROOT>to it in every command and agent prompt. - PLUGIN_ROOT:
${CLAUDE_PLUGIN_ROOT}. Skill and phase files write<PLUGIN_ROOT>/...because files opened with Read get no variable substitution; expand it to this absolute path before reading a file, running a command, or passing a path to an agent.
Core Process
Phase Overview
| Phase | Goal | Details |
|---|---|---|
| 0 | Setup | Inline below |
| 1 | Dispatch github-pr-reviewer agent | Inline below |
Phase 0: Setup
- Resolve
PROJECT_ROOTwith the command in Constants, before anycdor worktree switch, and use it for every.mz/path below. - Parse
$ARGUMENTS. If the PR reference is empty or malformed, escalate via AskUserQuestion — never guess, never fabricate a PR URL. - Normalize the reference to
<owner>_<repo>_<pr_number>form. task_name=<YYYY_MM_DD>_github_review_pr_<slug>where<YYYY_MM_DD>is today's date (underscores) and<slug>is<owner>_<repo>_<pr_number>truncated to 20 chars, snake_case; on same-day collision append_v2,_v3.- Create
<PROJECT_ROOT>/.mz/task/<task_name>/. - Write
<PROJECT_ROOT>/.mz/task/<task_name>/state.mdwithschema_version: 2,Status: running,Phase: 0,Started: <ISO timestamp>,PR: <reference>,Owner: <owner>,Repo: <repo>,Number: <pr_number>. - Emit a visible setup block:
task_name, PR reference, report dir (.mz/reviews/).
1. Dispatch
- Validate via
gh pr viewthat the normalized PR reference is accessible. On failure, escalate via AskUserQuestion. - Launch the
github-pr-revieweragent with the PR reference,task_name: <task_name>andproject_root: <PROJECT_ROOT>as the prompt. - After the agent returns, whatever its status, run
git worktree listand remove any leftover.claude/worktrees/pr-<pr_number>-*entry withgit worktree remove --force <path>. The agent removes its own worktree, but a turn limit or crash can stop it first. - Parse the agent's final message for the
STATUS:line:STATUS: DONEorSTATUS: DONE_WITH_CONCERNS→ updatestate.mdtoStatus: complete,Phase: 1. OnDONE_WITH_CONCERNS, also log the concerns block intostate.md.STATUS: NEEDS_CONTEXT→ re-dispatch once with the requested context; on a secondNEEDS_CONTEXT, escalate via AskUserQuestion.STATUS: BLOCKED→ escalate via AskUserQuestion with the blocker reason. Never auto-retry onBLOCKED.
- On any terminal success, display the absolute report path.
Red Flags
- The PR argument is missing or malformed and you are guessing a URL instead of asking.
- You dispatched
github-pr-reviewerwithout first validating PR accessibility viagh pr view. - The agent returned
STATUS: BLOCKEDorNEEDS_CONTEXTand you retried more than once instead of escalating. - The agent's final message had no
STATUS:line and you proceeded anyway.
Verification
Output the report path (.mz/reviews/<YYYY_MM_DD>_github_review_pr_<owner>_<repo>_<pr_number><_vN>.md), confirm the file exists, and print the VERDICT: line plus the count of Critical: findings.
Error Handling
- Empty / malformed PR argument → escalate via AskUserQuestion; never guess, never fabricate a PR URL.
ghunavailable for Phase 0 validation → before escalating, trymcp__*github*MCP tools if exposed. Only escalate via AskUserQuestion after bothghand MCP fail, and ask the user to authenticateghor connect a GitHub MCP server.- Missing tooling (
git worktreeunavailable,Agenttool absent) → escalate via AskUserQuestion with the exact missing command. - An agent returns nothing usable (report file missing, empty, or no
VERDICT:line) →<PLUGIN_ROOT>/shared/retry-policy.md: re-dispatch once with a clarified prompt, and don't retry API errors or usage limits. - Never guess — on any ambiguity (inaccessible PR, 404, merge conflict in worktree, missing base ref) escalate via AskUserQuestion rather than proceed silently.
State Management
State persists to .mz/task/<task_name>/state.md under the project root, ${MZ_MEMORY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}, resolved once at the start of the run. Schema is v2: line 1 is schema_version: 2; line 2 is Status: with one of pending, running, blocked, complete, aborted_by_user or failed, lowercase and unquoted; then Phase and Started. This skill runs setup, one dispatch and its report in a single turn with no approval gate, so it leaves out phase_complete and what_remains. Under a heading that reads exactly ## Lessons, add one line whenever a review finding is accepted and fixed or a step fails, in the form - (review|failure) WHEN <situation> → <what to do> — WHY <cause>, concrete and under about 40 words; mz-memory harvests lessons whatever the Status. On reading an older file, put schema_version: 2 on line 1 and Status on line 2, add no other keys, and log the upgrade. Leave a file with a higher schema_version untouched: ask whether to Restart (archive it), start New (_v2) or Abort, and stop if nobody can answer.