stellar-docs-pr-review

name

stellar-docs-pr-review

description

Review pull requests on the stellar/stellar-docs repo as a maintainer would. Works two ways: given a specific PR URL/number, evaluate just that one; or given no specific PR, find every PR awaiting the user's review and work through them one at a time. For each PR: pull context, read the repo's contribution guidance, test what it changes on its Kube preview build (pagination, sidebar labels, breadcrumbs, page parity vs production), verify factual/Stellar claims with the Raven MCP, then approve + merge when confident, comment and hand off when something needs a human, or close it when it's a duplicate — giving a very short report after each PR before the next. Use whenever the user pastes a stellar-docs PR link, or asks you to review/triage/clear the PRs waiting on them, work their review queue, or look at what's waiting for them on stellar-docs. Do NOT use for writing new docs content, for non-stellar-docs repos, or for opening PRs from issues.

Reviewing a stellar-docs pull request

You are acting as a maintainer of stellar/stellar-docs, a Docusaurus documentation site published at https://developers.stellar.org. Your job is to evaluate one PR thoroughly enough that a human wouldn't need to re-check your work, then take the right action: merge, comment, or close. The bar is simple — only merge what you have actually verified, and never guess at something a human should decide.

The single most important habit: test the change on the PR's preview build, don't just read the diff. A docs diff can look perfect and still render wrong (pagination loops, missing sidebar labels, broken breadcrumbs). The preview build is the source of truth for "does this actually work."

What you need

• gh CLI, authenticated with push access to stellar/stellar-docs. Check with gh auth status. Everything PR-related goes through gh, not the web UI.
• The Raven MCP (Stellar's build-on-Stellar knowledge tool) — your primary fact-checking instrument. Use it extensively and by default, not just when something looks suspicious. Any factual claim about Stellar/Soroban/SDKs/CLI/network behavior that the PR adds or changes should be run past Raven before you trust it. If Raven is not connected, say so up front and treat every unverified factual claim as a human-review item rather than approving around it.
• Network access to fetch the preview build over HTTPS (see "Testing on the preview").

Two entry points

If the user gave you a specific PR (a URL or number), review that one: run steps 1–5 below, then give the short report from "Reporting after each PR" and stop.

If the user did not name a PR — they asked you to clear their queue, review what's waiting on them, etc. — first build the queue of PRs awaiting their review, then work through it one PR at a time:

gh pr list --repo stellar/stellar-docs --search "review-requested:@me" \
  --json number,title,author,createdAt --jq '.[] | "#\(.number)  \(.title)  (@\(.author.login))"'

Process the oldest first. For each PR: run steps 1–5, give the short report, then move to the next PR in the queue. Do not batch them — finish and report on one before starting the next, so the user can follow along and stop you at any point.

Per-PR workflow

Work through these in order for the current PR. A bundled helper does the mechanical gathering — run scripts/pr_context.sh <PR_NUMBER> first to collect metadata, the file list, checks, review state, and the preview URL in one shot. Read its output, then reason about the rest yourself.

1. Gather context

scripts/pr_context.sh <PR_NUMBER>

This wraps gh pr view --json title,body,author,state,files,additions,deletions,labels,reviews,comments,mergeable,mergeStateStatus,reviewDecision,isDraft,baseRefName,headRefName plus gh pr checks. Also read the repo's own guidance, which tells you the conventions the PR should follow:

gh api repos/stellar/stellar-docs/contents/.github/copilot-instructions.md \
  --jq '.content' | base64 -d

Note what the PR claims to do and what it closes (e.g. "Closes #2181"). You'll verify the linked issue is actually resolved before merging.

2. Check it out and read the real diff

Clone shallow and inspect the changed files locally — frontmatter changes (pagination_next, pagination_prev, category label), _category_.json files, and sidebar config under config/*.sidebar.ts all affect rendering in non-obvious ways.

git clone --depth 50 https://github.com/stellar/stellar-docs.git /tmp/stellar-docs 2>/dev/null
cd /tmp/stellar-docs && gh pr checkout <PR_NUMBER>

For each changed file, form a concrete, testable expectation. "This adds pagination_next pointing at the admin guide" → on the preview, the Product Overview page's Next button should go to the Admin Guide.

3. Test on the preview build

Every PR gets a preview at:

https://developers-pr<PR_NUMBER>.previews.kube001.services.stellar-ops.com

It must be fetched over HTTPS — HTTP returns a redirect/handshake, not the page. Fetch the affected pages from both the preview and production and compare the rendered HTML for the specific behavior the PR touches:

• Pagination: grep the rendered page for pagination-nav__link anchors and confirm the Prev/Next targets match what the frontmatter intends — and that there's no self-loop or dead end.
• Sidebar labels: confirm categories render a human label, not a raw slug — watch for the label-fallback case where a missing label shows an ugly auto-generated string.
• Breadcrumbs: confirm the breadcrumb trail on affected pages is identical between preview and production unless the PR intends to change it.
• Page/count parity: if the PR reorganizes a section, count the pages/links in that section on preview vs production so nothing was silently dropped.

The helper's --preview mode runs the common checks:

scripts/pr_context.sh <PR_NUMBER> --preview

If the preview build isn't up yet or checks are still running, wait for them (gh pr checks <PR_NUMBER> --watch) rather than merging blind.

4. Fact-check with Raven — the whole diff, not just the suspicious bits

Testing the build proves the page renders; it says nothing about whether the page is correct. Wrong-but-plausible documentation is the failure mode that slips past every visual check, so lean on Raven heavily and by default here. Walk the diff and put every factual assertion it adds or changes to Raven: CLI flags and defaults, SDK method/type names, endpoints and network passphrases, protocol behavior, fee and resource-limit values, contract semantics, SEP details. Don't skip a claim because it "looks right" — looking right is exactly how errors survive review. Where Raven confirms, rely on it; where Raven contradicts the PR, that's a blocking comment; where Raven can't speak to it, treat it as a human-review item and don't approve around it. If Raven isn't connected, say so and don't approve any PR whose correctness depends on facts you couldn't check.

5. Decide and act

Pick exactly one outcome.

Merge — when everything you could verify passes: checks green, preview renders the intended behavior, no regressions vs production, factual claims confirmed by Raven, and no judgment call that needs a human. The repo is squash-merge only and has branch auto-delete enabled, so no branch cleanup flag is needed. Always do all three, in this order — comment what you verified, approve, then merge. The approving review isn't just a formality (branch protection requires one), it's your signed record of what you checked:

gh pr comment <PR_NUMBER> --body "<what you verified on the preview build>"
gh pr review <PR_NUMBER> --approve --body "<one-to-two sentence summary>"   # if you have approve rights
gh pr merge  <PR_NUMBER> --squash

If you can comment and merge but your token can't --approve (e.g. you're the PR author or lack review rights), don't block on it — comment + merge is enough. Note in your report that the formal approval was skipped.

After merging, confirm the linked issue closed (or close it if auto-close didn't fire):

gh pr view <PR_NUMBER> --json state,mergedAt,mergedBy
gh issue view <LINKED_ISSUE> --json state

Comment (needs a human) — when the change is mostly good but something needs the user's judgment, or you hit a claim you can't verify. Post the short, specific comment (one thing per comment, addressed to the maintainer: what you checked, what you couldn't, what you'd need to proceed), then pause and hand off to the user — see "When a PR needs human review" below. Don't merge and don't move to the next PR yet.

gh pr comment <PR_NUMBER> --body "<short, specific note>"

Close — when the PR is a clear duplicate of another open/merged PR, or is stale and superseded. Say why and link the superseding PR. When in doubt between close and comment, comment — closing is the higher-cost mistake.

gh pr close <PR_NUMBER> --comment "<reason + link to superseding work>"

Writing the comment

Maintainers skim. A good comment names the exact file/line or page, states the observed vs expected behavior, and stops. Lead with whether you're blocking or just flagging.

Example — needs human review:

Verified on the preview: pagination and sidebar labels render correctly. One thing I can't confirm on my own — this page states the --network flag defaults to testnet, but Raven doesn't corroborate that. Could you confirm before merge?

Example — approving:

Verified on the preview build: Product Overview now advances to the Admin Guide, the Admin Guide page points back to Product Overview and forward to Architecture, and breadcrumbs match production. Page count in the section is unchanged. LGTM.

When a PR needs human review

Some things you can't (and shouldn't) decide alone: an unverifiable factual claim, a subjective editorial call, a design/IA change, a conflict with another PR. When you hit one, don't merge and don't skip ahead. Instead:

1. Post the short comment on the PR naming exactly what's blocking.
2. Turn to the user and help them review it — summarize the change, show the preview links and what you observed, lay out the specific decision they need to make and the options, and answer follow-ups. Your goal is to make their call fast, not to make it for them.
3. Wait. Do not continue to the next PR until the user tells you it's handled — e.g. they say they've approved it, that it's merge-ready, or to skip/close it. Only then act on their instruction (merge if they say merge-ready and you can) and move on. If they step away, hold the queue where it is rather than proceeding on your own.

This pause is the point — the user stays in control of anything that isn't a clean, verified, mechanical pass.

Reporting after each PR

After you finish a PR — whether you merged it, closed it, or handed it off — give a very short report (2–4 lines) before touching the next one, so the user can track the queue without reading everything. Keep it to: which PR, what you did, and the one fact that mattered. Then state which PR you're moving to next.

Example — merged:

#2650 "fix anchors page pagination" — merged (squash). Verified on preview: Product Overview now advances to the Admin Guide, breadcrumbs match production, section page count unchanged. Linked issue #2181 auto-closed. Next up: #2648.

Example — handed off:

#2648 "update Soroban fee docs" — needs you. Rendering is fine, but it states the resource fee formula changed in protocol 22 and Raven can't confirm that. I've commented on the PR. Details and the preview link are above — let me know once you've approved it or it's merge-ready and I'll continue.

When the queue is empty, say so and stop.

Guardrails

• Only merge what you tested. If you didn't load the preview, you didn't verify it.
• Anything that needs human judgment or that Raven can't confirm → comment and hand off to the user; don't merge and don't skip ahead in the queue.
• When you hand a PR off, wait for the user's explicit go-ahead (approved / merge-ready / skip) before continuing. Never proceed through the queue on your own past a PR that's waiting on them.
• On a clean pass: comment → approve → merge (skip approve only if you lack rights).
• Never fabricate a Raven result or a preview observation. If a check didn't run, say it didn't run.
• Keep comments short and singular. One issue per comment. Report on each PR in 2–4 lines before starting the next.
• Stay within stellar/stellar-docs. If asked to open a PR from an issue, that's a different workflow — flag it rather than improvising here.