pr-review

name	pr-review
description	Verify the technical accuracy of a vscode-docs pull request against the VS Code source code in microsoft/vscode and microsoft/vscode-copilot-chat. Use when reviewing a docs PR for factual correctness — setting names, command IDs, default values, API shapes, keybindings, versioned availability, and described behavior.
argument-hint	<PR number or branch> (defaults to the current PR / branch)

PR Technical Accuracy Review

Review a vscode-docs pull request and verify every factual claim about VS Code behavior against the source code in microsoft/vscode and microsoft/vscode-copilot-chat. Produce an actionable list of findings the author can address before merging.

This skill checks technical accuracy only. It does not enforce writing style, frontmatter, or release-notes structure — use the release-note-writer or frontmatter-description skills for those.

When to Use

• Reviewing a vscode-docs PR that documents a new or updated VS Code or Copilot feature.
• Auditing existing docs for drift after a feature has changed.
• Asked to "fact-check", "verify", or "validate" a docs change against the product.
• Before merging a PR that touches docs/, api/, remote/, or release-notes content tied to a specific behavior.

Do not use this skill for pure copy-edits, redirects, image swaps, or other changes that make no factual claims.

Repos to Check

Area being documented	Primary source repo(s)
Core editor, workbench, debug, terminal, tasks, settings, commands, keybindings	microsoft/vscode
Copilot Chat, inline chat, agent mode, chat tools, chat participants, MCP integration in chat	microsoft/vscode-copilot-chat
Extension API, contribution points, package.json schema	microsoft/vscode (under src/vs/workbench/api/, src/vscode-dts/, and extensions/)
Enterprise policies	microsoft/vscode (policy definitions) — note that enterprise/policies.md is generated; verify against source, not the generated file

Use the gh CLI for all GitHub interactions (see user memory gh-cli-powershell.md for PowerShell-specific patterns).

Procedure

1. Identify the PR and its diff

• If a PR number was given, run gh pr view <number> --json number,title,headRefName,baseRefName,files,body to get metadata and the file list.
• If no argument was given, run gh pr view --json ... to use the PR for the current branch. If there is no associated PR, fall back to git diff origin/main...HEAD.
• Get the actual changed lines with gh pr diff <number> (or git diff for a branch).
• Skip files whose changes are purely cosmetic (typo fixes, image renames, redirect entries, frontmatter-only edits).

2. Extract verifiable claims

Walk the diff and build a list of every claim that can be checked against source code. Include line numbers from the new file content. Categories to look for:

Category	Examples
Setting	editor.fontSize, chat.agent.enabled, default values, allowed enum values, deprecation status
Command	Command IDs (workbench.action.*), command palette titles, the action they perform
Keybinding	Default key bindings, when clauses, platform-specific overrides
Menu / UI label	Menu item text, button labels, view titles, walkthrough step titles
API	Names, signatures, and shapes in vscode.d.ts / vscode.proposed.*.d.ts
Contribution point	package.json schema entries (contributes.*), required fields
Chat tool / participant	Tool names, participant IDs, tool input/output schemas, agent mode availability
MCP	Server config schema, supported transports, capability flags
Version availability	"Available since 1.X" / "New in 1.X" claims
Default behavior	What happens out-of-the-box, what is on/off by default
Policy	Policy names, supported values, scope

Treat anchor-style references (e.g., setting(chat.agent.enabled), command:workbench.action.X) as claims to verify.

3. Verify each claim

For every claim, locate the source of truth and compare. Prefer one targeted lookup per claim — do not download full files when a search will do.

Search the source repos (parallelize independent lookups):

• gh search code --repo microsoft/vscode '"<exact-string>"' for setting IDs, command IDs, contribution keys.
• gh search code --repo microsoft/vscode-copilot-chat '"<exact-string>"' for chat tool names, participant IDs, agent-mode flags.
• gh api "search/code?q=<query>+repo:microsoft/vscode" when the gh search CLI quotes the query in a way that breaks qualifiers (see user memory gh-cli-powershell.md).
• gh api repos/microsoft/vscode/contents/<path>?ref=main to read a specific file.

Where things live (common starting points):

• Settings — search for '<setting.id>' near registerConfiguration calls; default values are in the default: field of the schema.
• Commands — search for CommandsRegistry.registerCommand or registerAction2 with the matching id.
• Keybindings — search for KeybindingsRegistry.registerKeybindingRule or look in src/vs/workbench/browser/parts/editor/... and feature folders.
• Extension API — src/vscode-dts/vscode.d.ts (stable) and src/vscode-dts/vscode.proposed.*.d.ts (proposed).
• Chat tools — search microsoft/vscode-copilot-chat for displayName, toolReferenceName, or the tool ID string.
• Contribution points — extensions/<ext>/package.json and the schema in src/vs/workbench/api/common/extHost*.ts.

Version availability — when a doc claims "since 1.X":

• gh api repos/microsoft/vscode/contents/<file>?ref=release/1.X to see if the symbol existed in that branch, or
• gh search commits --repo microsoft/vscode '<symbol>' to find when it was introduced.

If a claim cannot be verified after a reasonable search, mark it Unverified rather than failing it — the author may have access to context the source does not expose.

4. Categorize each finding

Severity	Use when
Error	The doc contradicts the source code (wrong setting name, wrong default, wrong command ID, removed API, wrong key binding).
Warning	The claim is partially correct but misleading (default changed in a recent release, behavior is platform-specific and the doc does not say so, feature is behind a setting the doc does not mention).
Suggestion	Optional clarification — link to the source, add a "since 1.X" note, mention a related setting.
Unverified	Could not locate the source of truth; ask the author to confirm.

5. Produce the findings list

Output a Markdown report with this structure:

## PR Accuracy Review: #<number> — <title>

**Files reviewed:** <count>
**Claims checked:** <count>
**Result:** <Pass | Pass with warnings | Needs changes>

### Errors

* **`<file>`:L<line>** (`<category>`) — <one-line description>
  * Doc says: `<quoted text>`
  * Source: `<repo>/<path>#L<line>` — <what the source actually says>
  * Fix: <specific suggested correction>

### Warnings

* ...

### Suggestions

* ...

### Unverified

* **`<>`:L** — . Searched . Please confirm.

Rules for the report:

• Use workspace-relative paths and 1-based line numbers for vscode-docs files, formatted as Markdown links per the fileLinkification rules.
• For source-code citations, include the repo, file path, and (when known) line or commit. A gh-friendly URL is fine: https://github.com/microsoft/vscode/blob/main/<path>#L<line>.
• Quote the doc text exactly so the author can search for it.
• Keep each finding to one issue — split combined problems into separate items.
• If everything checks out, say so explicitly and skip the empty sections.

6. Summary

End with:

• Counts by severity.
• An overall verdict: Pass, Pass with warnings, or Needs changes (any Errors → Needs changes).
• A reminder that this review covers technical accuracy only, and to run style/frontmatter skills separately if needed.

Notes

• Do not push commits or post review comments on the PR unless the user explicitly asks. This skill produces a report for the user to act on.
• Do not edit enterprise/policies.md — it is generated; flag policy issues against enterprise/policies-template.md and the source policy definitions instead.
• When the doc references screenshots or videos, do not attempt to verify their contents — only verify any captions, labels, or alt text that make factual claims.
• Prefer main as the source-of-truth ref unless the PR explicitly documents behavior on a release branch or Insiders-only feature, in which case check release/1.X or recent commits accordingly.