Review PR

Review PR

Review incoming contributions for factual correctness and whether they make the documentation better as a whole. Treat a technically true addition as insufficient when it is misplaced, overemphasized, redundant, or unhelpful to the page's intended reader.

Preserve the write boundary

Perform the review in two phases:

1. Research the PR, decide a verdict, and present the exact proposed comment or review text.
2. Wait for explicit user confirmation, then post only the confirmed text.

Before confirmation, do not post comments, submit a GitHub review, approve or request changes, resolve threads, push commits, edit labels, or otherwise mutate GitHub. A request to review or draft feedback is not confirmation to post it. Ask Post these comments? and stop. Treat revisions to a draft as unconfirmed until the user explicitly asks to post them.

1. Gather the full context

For each PR, inspect its metadata, body, commits, changed files, checks, conversation, reviews, and linked issues. Always fetch inline comments separately because gh pr view --json reviews omits them.

gh pr view <PR> --repo docker/docs \
  --json number,title,url,state,author,body,baseRefName,headRefName,headRefOid,commits,files,comments,reviews,reviewDecision,statusCheckRollup
gh api repos/docker/docs/pulls/<PR>/comments \
  --jq '[.[] | {id, author: .user.login, body, path, line, side, commit_id}]'
gh pr diff <PR> --repo docker/docs

Read linked issues and relevant discussion. An issue is evidence that a reader was confused, but it does not establish the reporter's diagnosis or justify a new highlighted note by itself. Green CI establishes only that automated checks passed, not that the content is correct.

Fetch the PR head when local inspection is useful. Compare it with the canonical upstream base rather than assuming the local branch is fresh. Read each changed file in full, not only its diff.

2. Research independently

Verify every material claim against authoritative sources such as product source code, upstream documentation, specifications, release notes, or safe local reproduction. Do not accept the PR description, issue diagnosis, or existing review feedback as fact.

Search the documentation for related explanations and canonical pages. Read STYLE.md, COMPONENTS.md, and applicable repository instructions. Check whether a changed file is generated or maintained upstream and identify the correct upstream repository instead of proposing a local edit.

Distinguish among:

• a wrong fact
• a correct fact expressed inaccurately
• a correct fact placed on the wrong page
• content already explained elsewhere
• a real discovery problem better addressed with a short signpost and link
• a request that needs no documentation change.

If an external claim or replacement URL cannot be verified, report that limitation instead of guessing.

3. Assess editorial fit

Apply these questions to each addition:

• Does it change a reader's decision or next action on this page?
• Is this the canonical page for the concept?
• Is the fact general, or specific to this page, feature, or component?
• Is the information already documented elsewhere?
• Would a concise local signpost to canonical coverage solve the discovery problem better than duplicating the explanation?
• Is the visual and textual weight proportional to the information's value?
• Does it preserve the page's scope, flow, and character?

Prefer one coherent explanation in the canonical location. Add local context only when it helps the reader complete the task at hand. Avoid stray notes, callouts, and exhaustive edge cases whose prominence exceeds their value.

4. Choose a decisive verdict

Lead with one of these outcomes:

• Approve: correct, useful, well placed, and ready to merge.
• Approve with optional polish: ready to merge; suggestions are genuinely non-blocking.
• Focused rewrite: the underlying need is valid, but wording, scope, placement, or structure should change before merge.
• Close / no docs change: incorrect, redundant, out of scope, or not a documentation problem.

Explain the verdict with evidence. When wording is the issue, provide exact replacement text rather than a vague request to improve it.