Task: Review PR $ARGUMENTS

If you are in plan mode, exit it now. This is a read-only review task — nothing needs approval.

CRITICAL: READ-ONLY MODE

NEVER post comments, reviews, or any content on Josh's behalf. Not even if asked, unless Josh explicitly says to AND approves the exact text first.

You MUST NOT:

• Submit reviews (gh pr review)
• Post comments (gh pr comment, gh api POST/PUT/PATCH)
• Approve, request changes, or merge
• Modify any GitHub state whatsoever

gh pr checkout is allowed — it's a local git operation.

Your job is to present findings locally. Josh decides what to post.

Step 0: Parse arguments

$ARGUMENTS is a PR ref optionally followed by a note. The first token is the PR ref, everything after is a note providing additional context for the review.

Example: /pr-review 123 focus on the auth changes → PR ref: 123, note: focus on the auth changes

If the first token is not a PR ref, the whole of $ARGUMENTS is a note. $ARGUMENTS may also be empty.

If a note is present, treat it as guidance throughout the review — it may narrow scope, highlight concerns, or provide context.

Step 1: Resolve the PR reference

Resolve in this order, stopping at the first that produces a PR:

1. A PR ref in $ARGUMENTS

2. A PR ref or URL Josh named in the conversation

3. The PR for the current branch:

   GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
     gh pr view --json number,headRepository -q '.number'

If none of these resolve, ask in one line — no preamble: Which PR?

Parse a ref to determine the repo and PR number:

Get current repo owner if needed:

GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
  gh repo view --json owner -q '.owner.login'

Step 2: Confirm authorship, then announce

This skill reviews PRs authored by someone other than Josh. Check the author before doing anything else:

GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
  gh pr view <number> --repo <owner/repo> --json author,title,headRefName

Compare .author.login against $DOTFILES_GITHUB_USERNAME:

The handoff line when the author is Josh:

PR #123 is yours — switching to pr-feedback.

Otherwise announce the run in one line, then proceed without waiting for confirmation:

Reviewing PR #123 (read-only) — Add bandwidth endpoint

Step 3: Save state and checkout PR branch

ORIGINAL_BRANCH=$(git branch --show-current)
STASH_RESULT=$(git stash --include-untracked 2>&1)
GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
  gh pr checkout <number> --repo <owner/repo>

Track whether stash saved anything (check if $STASH_RESULT contains "No local changes").

Step 4: Gather PR context from GitHub

# PR metadata
GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
  gh pr view <number> --repo <owner/repo> --json title,body,state,author,baseRefName,headRefName,files,additions,deletions,commits,reviews,comments,reviewDecision,labels,createdAt,updatedAt

# Reviews
GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
  gh api repos/<owner>/<repo>/pulls/<number>/reviews

# Inline review comments
GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
  gh api repos/<owner>/<repo>/pulls/<number>/comments

# Issue comments
GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
  gh api repos/<owner>/<repo>/issues/<number>/comments

# CI status
GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
  gh pr checks <number> --repo <owner/repo>

Linked issues: Parse the PR body for issue references (Fixes #N, Closes #N, Resolves #N, or bare #N) and fetch each:

GH_TOKEN=$(gh auth token --user "$DOTFILES_GITHUB_USERNAME") \
  gh issue view <issue-number> --repo <owner/repo> --json title,body,state,labels,comments

Resolved review threads: These are context only. Read what was requested and what was done to resolve it. Do NOT re-raise resolved items as findings. Use them to inform your understanding of the PR's evolution if relevant, otherwise discard.

Step 5: Compute local diff (source of truth)

BASE_REF=<baseRefName from PR metadata>
git fetch origin "$BASE_REF"
BASE_SHA=$(git merge-base "origin/$BASE_REF" HEAD)

git diff --stat "$BASE_SHA"..HEAD
git diff "$BASE_SHA"..HEAD
git diff --name-only "$BASE_SHA"..HEAD

Never use gh pr diff — API diffs can be inaccurate. Local diff is the source of truth.

Step 6: Deep review via the code-reviewer agent

Dispatch the code-reviewer agent (Agent tool, subagent_type: code-reviewer) to do the actual review. It reads every changed file cold, traces code paths, re-derives claims by running them, sweeps for debug code, runs the documented tests and formatters, and returns findings without touching a file. The review criteria and output discipline live in the agent — don't restate them here.

Give it, in the prompt:

• The diff range: review "$BASE_SHA"..HEAD from Step 5, and tell it the base is already computed — the local diff is the source of truth, so it must not recompute the base or fall back to origin/HEAD
• The changed-file list from git diff --name-only "$BASE_SHA"..HEAD
• The requirement to measure against: the PR title and body, plus any linked-issue titles and bodies gathered in Step 4
• The note from Step 0, if present, as review guidance
• That this is a third-party PR review — read-only, post nothing

The agent returns a Findings list (each item as path:line — problem) and, when the work carried claims, a Claims block. Both are your input to Step 7, not Josh's output — you reshape them into copyable markdown there.

Step 7: Output

If the PR is clean — no bugs, no regressions, nothing substantial:

This PR is good to go. Approve it.

One line. Done. Do not elaborate, summarize changes, or praise the code.

If there are findings — output each as a raw markdown block wrapped in ```````` so Josh gets copyable markdown. Each finding is a separate block he can paste as a GitHub review comment.

Format for each finding:

````
`path/to/file.ts` line 42

Description of the problem — direct, specific, explains *why* it matters.

```suggestion
// corrected code here if applicable
```
````

• File path and line number (or range like lines 42-48) on the first line
• Problem description — plain language, no severity labels, no categories
• GitHub suggestion block only when you have a concrete fix. Omit if the fix is non-trivial or requires discussion.
• One finding per block. Do not combine multiple issues.

After all findings, one line:

Request changes — [N] items above.

Or if findings are minor enough to not block:

Approve with comments — [N] items above worth addressing.

Step 8: Restore original state

After completing the review, ALWAYS return to the original branch and restore stash:

git checkout "$ORIGINAL_BRANCH"
# Only if stash saved something:
git stash pop

Do this even if the review encounters errors.