Add docs-review skill for PR suggestions

.agents/skills/docs-review/SKILL.md

@@ -0,0 +1,203 @@
+---
+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. Use AGENTS.md and the style guide at `src/content/docs/style-guide/` as primary references.
+
+## 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 `references/content-rules.md` for the full checklist. 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`                                            |
+| Code block languages     | Must be lowercase and in the supported set (see AGENTS.md)                                           |
+| Internal links           | Absolute paths, no file extensions, no `https://developers.cloudflare.com`                           |
+| Heading hierarchy        | Sequential: H2 then H3 then H4 — never skip                                                          |
+| Frontmatter              | `title` required; `pcx_content_type` must be a valid value                                           |
+| Style guide              | Active voice, no contractions, "select" not "click", bold for UI elements                            |
+| Workers code             | Must use `TypeScriptExample` component, not bare `js`/`ts` fences                                    |
+| Config blocks            | Must use `WranglerConfig` component with TOML input                                                  |
+| 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 explain inline what other docs 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
+
+When posting suggestions, keep commentary minimal. One sentence of context, then the suggestion block.
+
+When posting a summary comment (not line-level), list issues by severity with file and line references. Severity levels: **CRITICAL** (build break, security) | **HIGH** (incorrect content, wrong API) | **MEDIUM** (missing component, outdated pattern) | **LOW** (minor style, wording)

.agents/skills/docs-review/references/content-rules.md

@@ -0,0 +1,78 @@
+# Content Review Rules
+
+Checklist for reviewing MDX documentation changes. Each rule includes what to check and how to fix it.
+
+## MDX Syntax
+
+| Check                                            | Fix                                                         |
+| ------------------------------------------------ | ----------------------------------------------------------- |
+| `{` `}` in prose (outside code blocks)           | Wrap in backticks or escape: `\{` `\}`                      |
+| `<` `>` in prose (outside code blocks)           | Use `&lt;` `&gt;` or wrap in backticks                      |
+| Component used without import                    | Add import from `~/components` after frontmatter            |
+| Code block without language                      | Add lowercase language identifier                           |
+| Unsupported code block language                  | Use `txt` for generic output; check AGENTS.md for full list |
+| Capitalized language name (`JSON`, `JavaScript`) | Use lowercase (`json`, `javascript`)                        |
+
+## Frontmatter
+
+| Check                      | Fix                                           |
+| -------------------------- | --------------------------------------------- |
+| Missing `title`            | Add a descriptive title                       |
+| Invalid `pcx_content_type` | Use a valid value from AGENTS.md list         |
+| Invalid `tags`             | Check against `src/schemas/tags.ts` allowlist |
+| `reviewed` date in future  | Set to today or a past date                   |
+
+## Links
+
+| Check                                                      | Fix                                         |
+| ---------------------------------------------------------- | ------------------------------------------- |
+| Full URL to docs (`https://developers.cloudflare.com/...`) | Use root-relative path (`/workers/...`)     |
+| Relative file link (`./page`)                              | Use root-relative path (`/workers/page/`)   |
+| File extension in link (`/workers/page.mdx`)               | Remove extension (`/workers/page/`)         |
+| Missing trailing slash (`/workers/page`)                   | Add trailing slash (`/workers/page/`)       |
+| Vague link text ("here", "this page", "read more")         | Use descriptive text: the target page title |
+
+## Headings
+
+| Check                                          | Fix               |
+| ---------------------------------------------- | ----------------- |
+| Skipped heading level (H2 then H4)             | Insert missing H3 |
+| H1 in content (only frontmatter title uses H1) | Demote to H2      |
+
+## Style Guide
+
+| Check                              | Fix                                                      |
+| ---------------------------------- | -------------------------------------------------------- |
+| Contractions ("don't", "can't")    | Expand ("do not", "cannot")                              |
+| "click" for UI actions             | Use "select"                                             |
+| "navigate to"                      | Use "go to"                                              |
+| "enable/disable"                   | Use "turn on/turn off"                                   |
+| UI element not bolded              | Bold clickable elements: **Save**, **DNS** > **Records** |
+| Code/paths/IPs not in monospace    | Wrap in backticks                                        |
+| `$` prefix in terminal commands    | Remove — copy button copies verbatim                     |
+| Two trailing spaces for line break | Use `<br/>`                                              |
+| Passive voice                      | Rewrite in active voice                                  |
+| "See" | Use "Refer to" |
+## Code Examples — Component Usage
+
+These checks are docs-specific (which component to use). For deeper code correctness (types, API usage, binding access, error handling, security), load the `code-review` skill.
+
+| Check                                     | Fix                                            |
+| ----------------------------------------- | ---------------------------------------------- |
+| Workers JS/TS in bare code fence          | Use `TypeScriptExample` component              |
+| Wrangler config in bare code fence        | Use `WranglerConfig` component with TOML input |
+| Hardcoded compatibility date              | Use `$today` in `WranglerConfig`               |
+| Package install without `PackageManagers` | Use `PackageManagers` component                |
+| `js` fence for Workers code               | Convert to TypeScript first                    |
+
+## Content Accuracy
+
+| Check                                                  | Action                                            |
+| ------------------------------------------------------ | ------------------------------------------------- |
+| Unverified API behavior claim                          | Verify against types or config schema (see below) |
+| Inline explanation of something with its own docs page | Replace with link to canonical page               |
+| Recommendation without rationale                       | Add brief "why" or link to supporting docs        |
+| Outdated API pattern                                   | Check latest types and update                     |
+| Nested tabs (tabs inside tabs)                         | Restructure into separate headings                |
+
+To verify API behavior, types, or config fields, use the same sources as the `code-review` skill: `node_modules/@cloudflare/workers-types/index.d.ts` for APIs and `node_modules/wrangler/config-schema.json` for config. Read these files directly — do not rely on pre-training.