--- name: Review PR Locally slug: review-pr-locally category: Automation description: Review PR Locally checks out an Azure DevOps or GitHub pull request into an isolated git worktree so a human can inspect it in their editor. It also posts only the review comments the human explicitly requests, using ADO tools or the gh CLI. github: "https://github.com/microsoft/FluidFramework/tree/main/.claude/skills/review-pr-local" language: TypeScript stars: 4944 forks: 585 install: "npx degit https://github.com/microsoft/FluidFramework/tree/main/.claude/skills/review-pr-local ~/.claude/skills/review-pr-local" installs_to: ~/.claude/skills/review-pr-local source_path: .claude/skills/review-pr-local/SKILL.md collection_size: 31 category_size: 1523 collection_url: "https://dirskills.com/collections/microsoft/FluidFramework" added: 2026-08-12T04:42:48.711Z last_synced: 2026-08-12T04:42:48.711Z canonical_url: "https://dirskills.com/skills/review-pr-locally" --- # Review PR Locally Review PR Locally checks out an Azure DevOps or GitHub pull request into an isolated git worktree so a human can inspect it in their editor. It also posts only the review comments the human explicitly requests, using ADO tools or the gh CLI. **Install:** ```bash npx degit https://github.com/microsoft/FluidFramework/tree/main/.claude/skills/review-pr-local ~/.claude/skills/review-pr-local ``` ## README # Review a PR Locally (ADO + GitHub) Check out a pull request into an **isolated git worktree** — never disturbing the user's current checkout — surface its changes in the editor, run an interactive review where the human drives, and post only the comments the human asks for. All identifiers are derived from the PR URL, so the skill works against any ADO or GitHub repository. ## Review Philosophy — high-signal, human-owned This is the core of the skill. Violating it defeats the purpose. - **The human drives the review.** The AI surfaces the parts worth attention and answers the human's questions. It never decides on its own to flood the PR with comments. - **Comments are posted only on explicit human request**, in one of two ways: 1. **Human-dictated:** the human gives exact location + text (e.g. `post comment on line 53 of src/foo.ts - this returns before the lock is released`). Post it verbatim. 2. **AI-drafted on request:** the human asks the AI to write a comment for a specific spot (e.g. `add a comment on the null check in bar.ts`). Draft it terse and high-signal, show it, and post only after the human approves. - **When surfacing "important parts," comment-worthy means:** correctness bugs, logic errors, security issues, breaking API changes, missing edge cases, data loss/corruption, race conditions, broken error handling. Ignore style, formatting, and naming. - **Never post** praise, summaries, restatements of what the code does, or style nits — in either mode. - **Every posted comment** cites a concrete `file:line` and is 1–3 sentences. ## Step 1 — Parse the PR URL Detect the platform and extract every identifier from the URL — nothing is hardcoded. | Platform | URL shape | Extract | |----------|-----------|---------| | Azure DevOps | `https://.visualstudio.com//_git//pullrequest/` or `https://dev.azure.com///_git//pullrequest/` | org, project, repo, id | | GitHub | `https://github.com///pull/` | owner, repo, number | If given a bare number instead of a URL, use `AskUserQuestion` to get the full URL (or the platform + identifiers). ## Step 2 — Prerequisites (self-contained) | Platform | Ensure tooling | Auth check → recovery | |----------|----------------|-----------------------| | Azure DevOps | `az extension show --name azure-devops` — if absent, `az extension add --name azure-devops` | `az account show`; on failure prompt the user to run `az login`, then stop | | GitHub | `gh --version` | `gh auth status`; on failure prompt the user to run `gh auth login`, then stop | For ADO, pass the org explicitly on every command: `--organization https://.visualstudio.com`. If any later `az` call fails with an auth error, prompt the user to re-run `az login`. ## Step 3 — Resolve PR metadata | Platform | Command | Fields | |----------|---------|--------| | Azure DevOps | `az repos pr show --id --organization https://.visualstudio.com --output json` | `sourceRefName`, `targetRefName`, `lastMergeSourceCommit.commitId` (head), `lastMergeTargetCommit.commitId` (base) | | GitHub | `gh pr view --repo / --json headRefName,baseRefName,headRefOid,baseRefOid` | `headRefName`, `baseRefName`, `headRefOid` (head), `baseRefOid` (base) | ## Step 4 — Fetch the PR into an isolated worktree Never run `git checkout` / `gh pr checkout` in the user's working directory. Always use a separate worktree. 1. Reuse an existing worktree if present: - Repo root: `git rev-parse --show-toplevel`. - Worktree path: sibling of the repo root named `-pr-`. - If it already appears in `git worktree list`, skip to Step 5. 2. Fetch the head and base commits: | Platform | Fetch head | Fetch base | |----------|------------|------------| | Azure DevOps | `git fetch origin ` | `git fetch origin ` | | GitHub | `git fetch origin pull//head` (works for forks) | `git fetch origin ` | 3. Create a **detached** worktree at the head commit (detached avoids "branch already checked out" errors and leaves no stray local branch): ``` git worktree add --detach ``` This writes the full tree and can take minutes on a large monorepo — use a long timeout and let it finish. ## Step 5 — Surface the PR changes in the editor The editor's Source Control panel shows only *uncommitted* changes, so a committed PR branch looks empty. Soft-reset the detached worktree to the PR's merge-base so the PR's changes become staged changes with per-file diffs. 1. Merge-base (isolates the PR's own changes): `git -C merge-base ` 2. Verify the real file set first: `git -C diff --stat ` 3. Surface as staged: `git -C reset --soft ` 4. Offer to open it: `code ` — changed files appear under **Staged Changes**. Tell the user not to run `git pull` there (it re-applies the commits and hides the diff); an already-open editor needs a Source Control refresh. ## Step 6 — Interactive review 1. Read the three-dot diff (`..`) and the modified files for context. 2. Present a short list of the **important parts** (per the Philosophy bar), each as `file:line` + a one-line reason. Default to few. 3. Answer the human's follow-up questions about any file, hunk, or symbol — read more of the tree as needed. Stay in this loop until the human is ready to comment or finish. ## Step 7 — Post comments the human requests Parse each request into `file`, `line`, and `body` (draft the body only if the human asked the AI to write it, then get approval). Post one comment per request. Read existing threads first to avoid duplicates. Anchor identifiers come from Step 1 (org/project/repo/id) and Step 3 (``). File paths are repo-relative. In the examples below, substitute the values parsed in Step 1 for every `<...>` placeholder. ### Azure DevOps — inline (anchored to a line) Preferred: the `ado/repo_create_pull_request_thread` MCP tool with a `threadContext`: ``` organization: project: repositoryId: pullRequestId: # integer content: "This returns before the lock is released." threadContext: filePath: "/" # leading slash rightFileStart: { line: , offset: 1 } rightFileEnd: { line: , offset: 5 } ``` REST fallback (when the `ado` MCP server is not configured) — uses the `az login` token: ``` az rest --method post \ --resource 499b84ac-1321-427f-aa17-267ca6975798 \ --uri "https://dev.azure.com///_apis/git/repositories//pullRequests//threads?api-version=7.1" \ --headers "Content-Type=application/json" \ --body @thread-body.json ``` where `thread-body.json` is `{ "comments": [{ "parentCommentId": 0, "content": "...", "commentType": 1 }], "status": "active", "threadContext": { "filePath": "/", "rightFileStart": { "line": , "offset": 1 }, "rightFileEnd": { "line": , "offset": 5 } } }`. Generate the body with a JSON serializer, not string interpolation. Delete the temp file afterward. ### Azure DevOps — general (PR-level) Same MCP tool or REST call, **omit** `threadContext` (and the body's `threadContext`). ### GitHub — inline (anchored to a line) ``` gh api --method POST /repos///pulls//comments \ -f body="This returns before the lock is released." \ -f commit_id= \ -f path= \ -F line= \ -f side=RIGHT ``` To post several inline comments as one review, batch them via `gh api /repos///pulls//reviews` (event `COMMENT`). ### GitHub — general (PR-level) ``` gh pr comment --repo / \ --body "Validation approach looks solid overall." ``` Rules for all paths: call ADO MCP tools server-qualified (`ado/repo_*`) — never `ado-repo_*` aliases; `pullRequestId` is an integer; prefer inline over general when the human gives a line. Confirm each post back to the human with the PR link. ## Step 8 — Cleanup When finished, remove the worktree (never affects the user's own branch): ``` git worktree remove --force ``` If the directory is locked (an editor still has it open), close that editor window, then re-run the remove and `git worktree prune`. ## Error handling - **Stale `origin`:** if the three-dot diff looks far larger than the PR, the local base ref is stale — re-fetch the base commit/branch and recompute the merge-base. - **Fork PR (GitHub):** always fetch via `pull//head`; don't assume the head branch exists on `origin`. - **Slow checkout:** the full-tree checkout on a large monorepo can take minutes — use a long timeout rather than interrupting.