docs-review

Review documentation changes for correctness, style, and structure.

Primary style reference: .agents/references/style-guide.md — read this before reviewing. It contains the canonical rules for MDX syntax, frontmatter, writing style, formatting, links, code blocks, and admonitions. The full style guide lives at src/content/docs/style-guide/ if you need to go deeper on any topic.

When to Suggest vs. When to Edit

Decision logic

1. Explicit instruction wins. If the user says "suggest", "only make suggestions", or "do not make changes" — post suggestions via gh CLI, never push commits. If they say "fix", "address this", or "update" — edit files directly and commit.
2. Different actor = suggest. If the person invoking the review is not the PR author (and no explicit fix instruction was given), post suggestions so the author retains control.
3. Same actor or ambiguous = fix by default. When the invoker is the PR author (or it is unclear), default to editing files directly. MDX syntax errors, broken code, invalid frontmatter, wrong component usage, and other obvious errors should always be fixed, not suggested.

Quick reference

When in doubt, fix obvious errors (build breakers, MDX syntax, wrong imports, broken code) and suggest subjective changes (wording, restructuring, style preferences).

Posting GitHub Suggestions

Use the GitHub REST API via gh api to post line-level suggestions on PRs. This is the only way to propose changes when operating in suggestion-only mode.

Prerequisites

Determine the PR number and the latest commit SHA before posting:

PR_NUMBER=$(gh pr view --json number -q '.number')
COMMIT_SHA=$(gh pr view --json commits -q '.commits[-1].oid')

Single-line suggestion

Replace one line in the diff. Use subject_type: "line".

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body='Tighten the phrasing:

```suggestion
Workers use an event-driven architecture. Each incoming request triggers a `fetch` handler.
```' \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/get-started/index.mdx" \
  -F line=42 \
  -f side="RIGHT" \
  -f subject_type="line"

Multi-line suggestion

Replace a range of lines. Add start_line and start_side.

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body='Simplify this paragraph:

```suggestion
Bindings provide direct, in-process access to Cloudflare services like R2, KV, and D1.
They require no network hop, no authentication token, and add no extra latency.
```' \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/runtime-apis/bindings.mdx" \
  -F start_line=18 \
  -F line=22 \
  -f start_side="RIGHT" \
  -f side="RIGHT" \
  -f subject_type="line"

Comment without suggestion

For feedback that does not map to a specific replacement, post a plain review comment (no suggestion block):

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body="This claim needs a source. Link to the relevant API reference or remove it." \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/observability/index.mdx" \
  -F line=55 \
  -f side="RIGHT" \
  -f subject_type="line"

Rules for suggestion blocks

• The content inside a suggestion fenced block replaces the target line(s) exactly. Include the full replacement text with correct indentation.
• For single-line: set line to the diff line number. Do not set start_line.
• For multi-line: set start_line to the first line and line to the last line of the range being replaced.
• Always set side to "RIGHT" (the new file side of the diff).
• Always set subject_type to "line".
• Line numbers refer to the new file in the diff (the right side), not the old file.
• Use -F (not -f) for numeric fields (line, start_line) so gh sends them as integers.
• Keep the prose before the suggestion block to one sentence. Do not over-explain.

Batching with a review object

When posting 3+ suggestions, use a single review with multiple comments to avoid notification spam:

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/reviews \
  --input - <<EOF
{
  "event": "COMMENT",
  "body": "A few suggestions for this PR.",
  "commit_id": "${COMMIT_SHA}",
  "comments": [
    {
      "path": "src/content/docs/workers/get-started/index.mdx",
      "line": 42,
      "side": "RIGHT",
      "body": "Tighten:\n\n\`\`\`suggestion\nWorkers use an event-driven model.\n\`\`\`"
    },
    {
      "path": "src/content/docs/workers/get-started/index.mdx",
      "line": 58,
      "side": "RIGHT",
      "body": "Fix link:\n\n\`\`\`suggestion\nFor more information, refer to [Bindings](/workers/runtime-apis/bindings/).\n\`\`\`"
    }
  ]
}
EOF

When using --input - with a heredoc, do not pass -f/-F flags — all fields go in the JSON body. The JSON must include event, commit_id, body, and comments.

Review Process

1. Read the Full Diff

gh pr diff ${PR_NUMBER}

Read full files for context — code that looks wrong in a diff may be correct in context. Check what section the change sits in and what comes before/after.

2. Check Against Rules

See .agents/references/style-guide.md for the full rules. Quick reference:

3. Assess What to Flag

4. Prioritize

Review in severity order:

1. Build breakers — unescaped MDX, missing imports, invalid frontmatter
2. Incorrect content — wrong API, wrong behavior description, broken examples
3. Missing best practices — no TypeScriptExample, hardcoded compat dates, bare code fences
4. Style and structure — heading levels, link format, prose quality

Content Review Principles

These principles are derived from recurring review feedback on this repo:

• Link to sources of truth. Do not re-explain concepts that have their own docs page. Link to the canonical page instead. Example: do not explain HTTP error 522 inline — link to /support/troubleshooting/http-status-codes/.
• Substantiate claims. If docs say "X behaves this way", verify it. Reference source code, API docs, or config schemas. Flag unverified claims.
• Be direct about recommendations. "Always use Hyperdrive when connecting to a remote PostgreSQL database" is better than "Connecting directly adds latency; consider using Hyperdrive."
• Qualify scope. "Bindings provide direct access to Cloudflare services like R2, KV, and D1" is better than "Bindings provide direct access to Cloudflare services" (which implies all services).
• Code examples must be safe to copy. Treat every code block as something a developer will paste into production. Examples must handle errors, use correct types, and follow current best practices.
• Use the right component. Workers code should use TypeScriptExample. Config should use WranglerConfig with $today for compatibility dates. Package install commands should use PackageManagers.
• Keep changes in scope. If a review uncovers issues in files outside the PR, note them but do not fix them in the same PR.
• Research before asserting. If uncertain whether an API, flag, or behavior is correct, look it up in the types, schema, or docs before flagging.

Output Format

<response_format> Your responses appear as GitHub comments. Every comment a reviewer reads costs attention. Be direct, be brief, and never repeat yourself.

Structuring responses

When posting inline suggestions, keep commentary to one sentence before the suggestion block. Do not over-explain.

When posting a summary comment, use this structure:

1. One-line verdict — what you did (for example: "Fixed 2 issues, posted 3 suggestions.") or your assessment (for example: "No issues found." or "2 issues need fixing before merge.").
2. Issues list — only items that need action, grouped by severity. Use severity labels: CRITICAL (build break, security) | HIGH (incorrect content, wrong API) | MEDIUM (missing component, outdated pattern) | LOW (minor style, wording). Include file path and line number for each.
3. Out-of-scope notes (optional) — pre-existing issues worth a future fix, kept to one or two sentences maximum.

That is the entire comment. Do not add anything else.

What to omit

• Do not list things that passed review. A review that finds 2 issues should mention 2 issues — not 2 issues and 15 things that were fine.
• Do not open with praise or qualitative assessments of the PR ("well-written", "solid PR", "technically sound"). Start with the verdict.
• Do not repeat information. If you posted inline suggestions, the summary comment should reference them briefly ("Posted 3 inline suggestions"), not restate each one.
• Do not create tables for fewer than 4 items. Use a flat list instead.
• Do not narrate your process ("I performed a section-by-section comparison", "I verified all 37 changes"). State the conclusion, not the method.
• Do not re-explain the PR's changes back to the author. They wrote it — they know what it does.

Follow-up responses

When responding to a follow-up request in the same thread (for example, "fix the build", "address the review comments"):

1. State what you changed, with file paths and line numbers.
2. Stop.

Do not re-run the full review. Do not re-summarize the PR. Do not repeat guidance from a prior comment. Each comment in a thread should contain only new information. </response_format>