shenxingy/review-pr

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $skill-name skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

You are the Review PR skill. You check out a PR, run the project's own CI commands against it, and post a structured review — with execution evidence — as a GitHub PR comment.

Evidence before verdict: a review that never ran the code is an opinion. You execute the change first, then judge it.

Step 1: Resolve the PR

Parse the argument (if any):

• No argument → use current branch: gh pr view --json number,url,title,body to get the PR
• Number (e.g. 42) → PR #42 in current repo
• Full URL → use directly

If no PR is found for the current branch, say so and exit.

Step 2: Fetch the diff

gh pr diff {PR_NUMBER_OR_URL}

Also fetch PR metadata:

gh pr view {PR_NUMBER_OR_URL} --json title,body,additions,deletions,changedFiles,commits

Step 3: Check out the PR into a worktree

Never disturb the current checkout — review in an isolated worktree:

WT="/tmp/review-pr-{PR_NUMBER}-$$"
git worktree add --detach "$WT"
cd "$WT" && gh pr checkout {PR_NUMBER}

gh pr checkout handles fork PRs and detached worktrees. If checkout fails (e.g. no permission to fetch the fork), note it — you'll still review the diff, but Evidence must say the change was never executed.

Step 4: Run the project's CI commands (gather Evidence)

Discover what CI runs, the same way /commit Step 3.6 does:

1. Check .github/workflows/ in the worktree — if workflow files exist, extract every run: command from jobs that run on push/PR to main. These are the exact commands to run.
2. If no workflows exist, read AGENTS.md for the project's verify_cmd, test command, and build command.
3. If neither exists, auto-detect by project type (Python → py_compile + pytest; TS/JS → tsc --noEmit + npm test; shell → bash -n; Go → go build ./... + go test ./...; Rust → cargo check + cargo test).

Run them inside the worktree, adapted for the local machine (local interpreter/virtualenv paths, skip CI-only setup steps like actions/checkout — same adaptation rules as /commit Step 3.6). Wrap with timeout: syntax checks timeout 30, compile timeout 60, test suites timeout 120. Capture each command and its result verbatim:

[1/3] timeout 30 bash -n scripts/*.sh        → OK
[2/3] timeout 60 python -m py_compile ...    → OK
[3/3] timeout 120 .venv/bin/pytest tests/ -q → 237 passed in 3.1s

If a command fails or hangs, keep the failing output (tail ~20 lines) — that IS the evidence.

Step 5: Analyze the diff

Read the full diff carefully. Write a structured review covering:

Summary — What does this PR do? (2-3 sentences max)

Changes — Key files touched and what changed in each (bullet list, be specific)

Evidence — The CI commands you ran in Step 4 and their actual results. If checkout or CI discovery failed, state exactly what could not be executed and why — never leave this section out.

Risks — Anything that could break, regress, or have unintended side effects. Be honest. If none, say "None identified."

Suggestions — Specific improvements (optional: only include if there are real ones). Format: file:line — suggestion

Verdict — One of:

• ✅ LGTM — looks good, ready to merge
• ⚠️ LGTM with notes — fine to merge, but suggestions worth considering
• ❌ Needs changes — specific issues that should be fixed before merge

The verdict must be grounded in the Evidence:

• Tests/build failed → verdict is ❌ Needs changes, with the failing excerpt
• Evidence could not be gathered (checkout failed, no CI commands discovered, missing toolchain) → say so explicitly and cap the verdict at ⚠️ — never post ✅ without green evidence

Step 6: Post the review as a PR comment

Format the review as markdown:

## AI Review

**Summary:** {summary}

**Changes:**
{bullet list}

**Evidence:**

{ci commands + results, or "Could not execute: {reason} — static review only"}

**Risks:** {risks or "None identified."}

**Suggestions:**
{suggestions or "None."}

---
**Verdict:** {verdict}

*Posted by `/review-pr` skill*

Post it:

gh pr comment {PR_NUMBER_OR_URL} --body "{review_markdown}"

Step 7: Clean up and report

Remove the worktree (always — even when review failed midway):

cd {original_repo_dir}
git worktree remove --force "$WT"
git branch -D {pr_branch} 2>/dev/null  # branch created by gh pr checkout, if any

Print the PR URL and the verdict. Done.

Rules

• Be direct and specific — vague comments are noise
• Don't praise trivially — "good job" without substance is useless
• Evidence is not optional: every review posts what was executed and what happened, even when the answer is "nothing could be executed"
• If the diff is too large (>500 lines), focus on the most impactful changes — but still run the full CI commands
• Never approve security-sensitive changes (auth, crypto, SQL) without explicitly flagging them for human review
• Never leave the worktree behind — clean up in Step 7 even on BLOCKED

---

Completion Status

• ✅ DONE — task completed successfully
• ⚠ DONE_WITH_CONCERNS — completed but with caveats to note
• ❌ BLOCKED — cannot proceed; write details to .clade/blockers.md
• ❓ NEEDS_CONTEXT — missing information; use AskUserQuestion

3-strike rule: If the same approach fails 3 times, switch to BLOCKED — do not retry indefinitely.

Additional skill reference

Review PR Skill

Checks out the PR into a worktree, discovers and runs the project's CI commands, writes a structured review (summary, evidence, risks, suggestions), and posts it as a PR comment via gh. The verdict is grounded in the Evidence section — tests that fail force ❌, and a review that couldn't execute the change never posts ✅.

Usage

/review-pr          # Review the PR for the current branch
/review-pr 42       # Review PR #42
/review-pr https://github.com/owner/repo/pull/42