reviewing-external-prs

Files (1)

• SKILL.md

SKILL.md (first lines)

# Reviewing External PRs

Two-phase PR review: Phase 1 checks out the PR and runs the review orchestrator. Phase 2 (in a new thread after handoff) converts findings to conventional comments and posts them.

## Prerequisites

- `gh auth status` must pass

## Phase 1: Checkout + Orchestrate (This Thread)

### 1. Checkout PR Locally

Try in order until one works:

```bash
# Method 1: wt-continue (preferred)
which wt-continue && wt-continue <repo-name> "$(gh pr view <N> --repo <OWNER/REPO> --json headRefName -q .headRefName)"

# Method 2: git fetch PR ref (most reliable for forks)
gh repo clone "https://github.com/<OWNER>/<REPO>.git" /tmp/review-<REPO>-<N> -- --depth=100
cd /tmp/review-<REPO>-<N>
git fetch origin pull/<N>/head:pr-<N>
git checkout pr-<N>

# Method 3: gh pr checkout (sometimes fails for forks)
gh pr checkout <N>
```

Confirm: `pwd && git branch --show-current`

### 2. Gather PR Context

```bash
BASE=$(gh pr view <N> --repo <OWNER/REPO> --json baseRefName -q .baseRefName)
git fetch origin "$BASE"

# Write PR context for the review bundle
PR_CONTEXT=$(gh pr view <N> --repo <OWNER/REPO> --json title,body,author --template '{{.title}} by {{.author.login}}
{{.body}}')
```

### 3. Run Review Orchestrator

Load the skill:

```json
{ "name": "review-orchestrator" }
```

Follow the orchestrator workflow with:

- **Base ref:** `origin/${BASE}`
- **PR context:** pass to `gather-context.sh`
- **Note:** B-group usually skipped (no node_modules in temp clones). Minimum viable: A2-A11, A13, A15-A16 + C2.

**Do NOT manually review files instead. Do NOT use `gh pr diff`. Do NOT install deps.**

### 4. Mandatory Handoff After Triage

After the orchestrator triage completes, **you MUST hand off** to a new thread for Phase 2. Use the `handoff` tool:

```
goal: "Phase 2 of external PR review for <OWNER/REPO>#<N>. Load the reviewing-external-prs skill. Review artifacts are in <REPO_PATH>/.review-orch/compiled.md with triage decisions. Convert selected findings to conventional comments, get human approval, post as batched review, and reassign PR. Repo path: <REPO_PATH>, PR: <N>, Owner/Repo: <OWNER/REPO>, Base: <BASE>"
follow: true
```

**Do NOT attempt Phase 2 in this thread.** Context is exhausted by the orchestrator.

---

## Phase 2: Post Comments (New Thread After Handoff)

### 5. Convert Findings to Comments

Read `.review-orch/compiled.md` from the repo path. Convert each **selected** finding to conventional comment format:

| Orchestrator Severity | Conventional Label                         |
| --------------------- | ------------------------------------------ |
| Critical              | `issue:` or `todo:` (blocking)             |
| Major                 | `issue:` or `suggestion:`                  |
| Minor                 | `suggestion: (non-blocking)` or `nitpick:` |
| Nitpick               | `nitpick: (non-blocking)`                  |

Exclude only: praise, exact duplicates, factually wrong findings (verify before dropping).

### 6. Present for Approval

```
[1] src/Foo.vue:42 - question
Draft: question: both key and label are set to item.id. Is that intended?

[2] src/parser.ts:128 - nitpick
Draft: nitpick (non-blocking): this split assumes no delimiter in values.

---
Which to post? Numbers ("1, 2"), "2cr" for @coderabbitai issue, "all", "none"
```

Wait for human decision. `cr` suffix appends `\n\n@coderabbitai Make an Issue to do this in a followup PR on a future date`.

### 7. Choose Review Event Type

```
Submit as: 1) COMMENT  2) APPROVE  3) REQUEST_CHANGES
```

Guidelines: all nits → APPROVE, blocking issues → REQUEST_CHANGES, questions → COMMENT.

### 8. Show Final Review + Post

Show exact review, wait for confirmation, then post as single batched review:

```bash
gh api repos/<OWNER>/<REPO>/pulls/<N>/reviews \
  --method POST \
  --input <(cat <<'EOF'
{"commit_id":"<SHA>","event":"COMMENT","body":"","comments":[...]}
EOF
)

From DrJKL/ticket-to-pr-pipeline, MIT.

More from DrJKL/ticket-to-pr-pipeline