docs-review

---
name: docs-review
description: Reviews documentation PRs and provides GitHub PR suggestions. Load when asked to review, suggest changes, or provide feedback on docs content. Covers MDX, frontmatter, style guide, components, and content accuracy.
---

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

| Instruction                                        | Action                                                                |
| -------------------------------------------------- | --------------------------------------------------------------------- |
| "review", "suggest changes", "provide suggestions" | Post **suggestions only** via `gh` CLI — do not push commits          |
| "only make suggestions", "do not make changes"     | Post **suggestions only** — never edit files or push                  |
| "fix", "address this", "update"                    | Always edit files directly and commit changes                         |
| "review and fix"                                   | Fix low-severity issues directly; suggest high-impact changes         |
| Invoked by someone other than PR author            | Post suggestions unless explicitly told to fix                        |
| Invoked by PR author (or unclear)                  | Fix directly — especially MDX syntax, code errors, and build breakers |

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:

```bash
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"`.

````bash
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`.

````bash
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):

```bash
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:

```bash
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

```bash
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:

| Rule                     | Detail                                                                                               |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| Unescaped MDX characters | `{`, `}`, `<`, `>` in prose must be escaped or in backticks                                          |
| Component imports        | Every component used must be imported from `~/components`                                            |
| Workers code             | Must use `TypeScriptExample`, not bare `js`/`ts` fences                                              |
| Config blocks            | Must use `WranglerConfig` with TOML input; use `$today` for `compatibility_date`                     |
| Package install commands | Must use `PackageManagers`, not bare `sh` fences                                                     |
| Code block languages     | Lowercase, from the supported set — see `.agents/references/style-guide.md`                          |
| Internal links           | Root-relative paths, trailing slash, no file extensions, no full `developers.cloudflare.com` URLs    |
| Frontmatter              | `title` and `description` required; `pcx_content_type` must be a valid value                         |
| Writing style            | See `.agents/references/style-guide.md` — covers voice, contractions, terminology, headings, etc.    |
| Code correctness         | For type checking, API usage, and binding patterns, load the `code-review` skill                     |
| Accuracy                 | Claims must be substantiated — link to sources of truth, do not re-explain what other pages cover    |

### 3. Assess What to Flag

| Flag                                                            | Do not flag                                          |
| --------------------------------------------------------------- | ---------------------------------------------------- |
| Incorrect technical content                                     | Style preferences not in the style guide             |
| Broken MDX (build will fail)                                    | Pre-existing issues in unchanged lines               |
| Wrong API usage or types                                        | "Could be cleaner" when code is correct              |
| Missing component usage (`TypeScriptExample`, `WranglerConfig`) | Theoretical concerns without evidence                |
| Inaccurate or unsubstantiated claims                            | Missing features outside the PR scope                |
| Security or safety issues in examples                           | Minor wording differences that do not change meaning |
| Scope creep (changes to files outside the PR intent)            |                                                      |

### 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>