docs-review-pr

• Never edit a file. Never write a file outside the scratchpad.
• Never post to GitHub. Never run

  gh pr review

  ,

  gh pr comment

  , or

  gh pr merge

  .
• Dispatch every companion skill in report-only mode, so the guarantee holds transitively. Two companions can write if you let them:

  docs-applies-to-tagging

  declares

  Edit

  and its validate mode reports or fixes, and

  docs-validate-code-samples

  declares

  Write

  and can write an output file. Both go through the subagent path only, where the spawn prompt can forbid writes — see Step 3.
• The one exception is

  gh pr checkout

  in Step 1, which you offer and never run without the user saying yes.

$BASE

$BASE_REPO

git fetch "https://github.com/.git" ""

gh pr view

baseRepository

BASE=$(gh pr view <n> --json baseRefName -q .baseRefName)
BASE_REPO=$(gh pr view <n> --json url \
  -q '.url | capture("github\\.com/(?<r>[^/]+/[^/]+)/pull").r')

@{u}

BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null) \
  || BASE=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
BASE_REPO=$(gh repo view --json parent,nameWithOwner \
  -q 'if .parent then .parent.nameWithOwner else .nameWithOwner end')
git fetch "https://github.com/$BASE_REPO.git" "$BASE"
git diff -U0 "$(git merge-base HEAD FETCH_HEAD)"...HEAD

• gh pr view

  with no number resolves the current branch's PR when one exists, which is the most reliable answer about what a branch targets. When it succeeds, the branch is not PR-less: reuse that PR's metadata for labels, author, and body rather than reporting the PR-only checks as skipped.
• Fetch the base branch from the base repository, not from

  origin

  . In a fork clone

  origin

  is the fork, so

  origin/main

  is the contributor's copy of main — stale, or missing entirely — and diffing against it gives a wrong changed-file set. Fetching by URL into

  FETCH_HEAD

  sidesteps the question of what any local remote happens to point at.

1. git rev-parse HEAD

   must equal

   headRefOid

   . That single check subsumes branch name, fork, and staleness — a matching commit is a matching tree.
2. If it does not match, check that you are in the right repository before anything else. Compare

   gh repo view --json nameWithOwner

   against the PR's base repository — the

   owner/name

   in the PR URL — by

   owner/name

   , never by remote URL string, since the SSH and HTTPS forms of one repo differ as text.

headRepository

isCrossRepository: true

gh pr checkout

headRepository

• Commit matches — proceed.
• Not a git repo, or not the PR's base repo — stop. Tell the user which repo to run from.
• Right repo, wrong ref — check for uncommitted work first with

  git status --porcelain --untracked-files=no

  . Only tracked modifications block a switch: if there are any, do not offer to check out, and tell the user to stash or commit. Untracked files do not block, because

  gh pr checkout

  leaves them alone — mention them and carry on. When nothing is blocking, ask whether to run

  gh pr checkout <n>

  , and wait for an answer. Never check out without one.
• User declines the checkout — continue in degraded mode. Write each changed file to its own scratchpad path, preserving the repo-relative structure, and review those copies:

  SCRATCH=$(mktemp -d)                       # create it once, reuse for every file
  mkdir -p "$SCRATCH/$(dirname <path>)"
  gh api "repos/{owner}/{repo}/contents/<path>?ref=<headRefOid>" --jq .content \
    | base64 -d > "$SCRATCH/<path>"

  Create

  $SCRATCH

  before the first fetch and report the path, so the user can inspect what you reviewed.
  Redirecting to a file is the point — decoded content on stdout gives the later Read, Grep, and companion steps nothing to open. Dispatch companions against the scratchpad paths. Mark every repo-hygiene check in Step 4 as Not checked — ran against a different ref, because the rest of the repo is still at the wrong commit. Do not report them clean.

Skill

elastic-docs-skills

docs-validate-code-samples

disable-model-invocation: true

SKILL.md

1. Skill

   tool — read-only companions only, per the Path column. Pass one file to review as

   args

   . Use the plugin-prefixed frontmatter name,

   elastic-docs-skills:docs-content-type-checker

   , which is the form the README documents. Fall back to the bare name if the prefixed one is refused. A copy installed as a project skill under

   .claude/skills/

   answers to its directory name, not its frontmatter

   name

   , so try that form last.
   A companion that declares

   Edit

   or

   Write

   never goes down this path.

   args

   is the only thing you control on a

   Skill

   call, and asking politely for validation is not a guarantee:

   docs-applies-to-tagging

   treats a file path as validate mode, and validate mode still reports or fixes. The subagent spawn prompt is the only channel that can actually forbid a write, so

   applies-to-tagging

   and

   docs-validate-code-samples

   always use path 2, even when the

   Skill

   tool would accept them.
   One changed file per call. Companions declare

   <file-or-directory>

   and glob

   $ARGUMENTS

   , so a space-separated list is read as one bad path, not many good ones. Invoke once per changed file. Pass a directory only when it contains exactly the changed set and nothing else — otherwise the companion globs unrelated pages and their findings leak into the report and skew the recommendation. When in doubt, one file per call. This applies to both dispatch paths.
2. Subagent. The required path for write-capable companions, and the fallback whenever both

   Skill

   name forms are refused or unlisted. Spawn one subagent per companion, all in a single message so they run in parallel. Each subagent:
   • Locates the companion's

     SKILL.md

     by globbing

     ~/.claude/skills/*/SKILL.md

     ,

     ~/.claude/plugins/**/skills/**/SKILL.md

     , and the local repo's

     skills/**/SKILL.md

     , matching on either the directory name or the frontmatter

     name:

     field.
   • Executes those instructions verbatim against the changed files, substituting a single path for

     $ARGUMENTS

     — one file, or the common parent directory — following the same one-target rule as path 1.
   • Returns a compact findings list: file, line, severity, finding. Not the companion's full report.
   Reading the rubric from the companion is what keeps this skill thin. Never copy a companion's rules into this file.
3. Not installed. If a companion is nowhere to be found, mark its criterion Not checked —

   <skill>

   not installed and give the install command:

   npx --yes skills@latest add elastic/elastic-docs-skills --skill <name> -g

   Use the companion's frontmatter

   name:

   —

   docs-check-contradictions

   , not its

   check-contradictions

   directory. That is what the install command takes. The invocation name is a separate question: a copy installed as a project skill under

   .claude/skills/

   answers to its directory name instead, so try that form before reporting a companion as not installed.

• Do not write findings for that companion's criterion yourself, and do not label the gap a manual assessment. Your own checks are Step 4's list; they are not a substitute for a companion's rubric, which is the whole reason the companion exists.
• Mark the criterion Not checked, say which companion and why, and leave it at that. A criterion that looks covered because you filled it in by hand is worse than an admitted gap, because nobody can tell the difference in the report.
• The exception is a finding you genuinely made yourself under Step 4. Source it

  docs-review-pr

  and keep it in its own row — never merge it into a missing companion's slot.

Skill

Do not Edit or Write any file. Do not modify the working tree. Return findings only.

• Do not begin Step 5 until every dispatched companion has returned.
• Never predict, summarize, or invent what a pending companion will say. Fabricating companion output is the worst failure this skill can have, because the report format makes it look attributed and verified.
• If a companion errors or never returns, mark its criterion Not checked — companion did not return and carry on with the rest. Do not fill the gap with your own assessment; see Never stand in for a companion that did not run.

• Change serves the user's task and sits in the correct place on the page.
• Paragraphs are short, and lists, tables, and admonitions break up dense content.
• Lead-in sentences set topic boundaries and tell the reader how to think about what follows.
• The benefit of the feature or path is stated, not only its mechanics. Check this in three places: the intro/description (user benefit, not just mechanics), each decision point (tradeoff, not just description of both options), and the title (does the page deliver what the title promises?).
• All impacted pages are assessed and updated, including reference pages that use a newly introduced concept.
• A new feature is contextualized on its parent page against the product landscape.
• The page declares its content type in frontmatter as

  type:

  . When

  docs-content-type-checker

  identifies the page as a how-to, tutorial, overview, or troubleshooting page and the frontmatter carries no

  type:

  field, recommend adding it — naming the type it should be. Do this for edited pages, not only new ones: an existing page never passed through a template, so the field is the one most often missing. Recommend it even when nothing consumes the field yet. Structural findings about a content type without the tag that names it leave the reader to infer what you already determined.

• The page sits in the correct place in the information architecture.
• Cross-references point into the page from its parents, so users are not stranded. Grep the repo for links into any new or moved page.
• Headings run about 50–60 characters where practical, and describe the page distinctly from similar ones.
• The page discloses progressively: the reader gets what they need in the order they need it.
• Warnings and cautions appear before the step or content they warn about, not after.
• Conceptual choices use contrasting pairs, options carry value propositions near the decision point, and branching decisions use nested navigation.
• No existing page already covers this ground. Check with the

  elastic-docs

  MCP tool

  find_related_docs

  on the page topic.

• Look in the PR body, review comments, branch name, and any linked issue for an SME sign-off, an eng review, or an authoritative source.
• Check whether new code samples are described as tested.
• State plainly which it is: evidence present and where, or evidence absent. Never infer technical correctness from confident prose.

elastic/elasticsearch#12345

1. Resolve the reference and read both sides:

   gh pr view <n> --repo <owner/repo> --json title,body,state,mergedAt,baseRefName,files
   gh pr diff <n> --repo <owner/repo>

   Pass the number with

   --repo

   , or a full PR URL. The shorthand

   gh pr view elastic/elasticsearch#12345

   does not work —

   gh

   reads it as a branch name and reports no PR found, which looks like a missing PR rather than a bad command.
2. Pull the checkable facts out of the code diff: setting, flag, and parameter names; default values, limits, and enum values; error and log message text; and any added or changed tests, which assert intended behavior more reliably than comments describe it.
3. Compare each against what the docs change asserts. Report under Technical accuracy, citing the code PR and the file in its diff, so the writer can follow the same trail.

• Version. The code PR's

  baseRefName

  tells you which branch it landed on. Cross-check that against the page's

  applies_to

  . Docs tagged for 9.2 describing a change that landed on 8.19 is a real finding, and one nothing else in this review would catch.
• Merge state. An unmerged code PR describes intended behavior that can still change. Say so rather than treating it as settled.
• Absence proves nothing. A docs claim missing from the code diff is not wrong — the diff is one change, not the whole product. Only flag a direct conflict: the docs say one value, the code says another.
• Matching is not verification. Report what matched and where. Never write that a change is technically correct because a diff agreed with it; the same rule that governs confident prose governs confident diffs.

• Prerequisites are still accurate after the change, covering permissions, setup, and assumed knowledge.
• No new permission or setup dependency is left unstated.
• Deployment types and versions are called out in prerequisites when they differ from page-level tagging.
• Deployment scope is correct: relevant types are covered or signposted, shared processes stay deployment-agnostic, and self-managed, ECE, and ECK are treated as distinct deployment types rather than collapsed into one customer-operated group. They share core Elasticsearch functionality; the difference is how a deployment is run, not what it can do.

• No procedure or value is duplicated from somewhere it already lives. A cross-reference or a snippet is better. When a section embeds reference material (parameter descriptions, format explanations, API syntax, full procedures), use

  find_related_docs

  or

  search_docs

  to check whether a dedicated page already covers it. Flag intra-page duplication too — read Option 1 and Option 2, or Method A and Method B, side by side.
• No remaining page links to or references a deleted or moved page by its old path. Grep the repo for the old path and for its anchors.
• No deleted image or snippet is still referenced by another page. Grep the repo for each removed asset path.
• Every renamed, moved, or deleted page has a matching redirect entry, including renamed anchors. Flag a missing one High, because it breaks live links. The file is

  redirects.yml

  or

  _redirects.yml

  , next to the content set's

  docset.yml

  or

  _docset.yml

  — check both names before reporting one missing, or you will raise false findings.
• No generated or automated reference material is hand-edited. The fix belongs at the source.
• Screenshots, diagrams, and non-Elastic external links earn their ongoing maintenance cost.

• The change commits to no roadmap items and no future plans.
• The change carries no implementation details or decision history that users do not need.

• No literal

  {{

  reaches the rendered output, and every substitution resolves.
• No admonitions are stacked back to back. Merge them into one callout or into the narrative. Scan for consecutive pairs — two admonitions separated only by whitespace count as stacked even if each looks fine individually.
• Roughly three or fewer admonitions sit in one area, so they still stand out.
• No stray bullets, leftover comments, or broken tables and tabsets appear.
• Badges render, and section- or line-level

  applies_to

  tags work alongside page-level tags.
• Link text is meaningful, and new or changed links resolve.

• Backporting labels are present and correct for the target branches. Read them with

  gh pr view --json labels

  .
• No unfinished content remains: TODOs, placeholder text, or commented-out drafts.
• The title and H1 are still accurate and in sentence case after the change.

| Severity | file:line | Finding | Guideline | Source |

• Severity — High when a user following the page fails or is misled, or when live links break. Medium when the content is inconsistent or unclear but still usable. Low for nuance.
• Guideline — a link to the rule that decides the finding, from the Rule citations table in

  references/review-criteria.md

  . Link the section anchor when the table lists one, otherwise the page that governs the criterion. Cite the rule the finding actually rests on, not the section it happens to sit in: a missing

  description

  is a metadata and findability rule, not

  seo#headings

  ; an ambiguous trigger condition is a clarity problem, not

  grammar-spelling

  . A criterion name such as "Technical accuracy" is not a citation — it names where the finding is filed, not what decides it. If nothing in the table fits, leave the column empty rather than reaching for the nearest link; a wrong citation sends the writer to a rule that does not say what you claim. The column holds a link or nothing — a bare word such as

  findability

  , or a criterion name, is not a citation and must not appear there. Every Language and Style finding must carry one, and so must any other finding a specific page decides. A writer who disagrees needs somewhere to go and check; "the style guide says so" is not a citation. When a companion reports a rule name of its own, such as a Vale rule like

  Elastic.OxfordComma

  , include that too, so the writer knows which check fired. Never invent an anchor — if nothing listed covers it, cite the page and say which part applies.
• Source — which companion skill produced it, or

  docs-review-pr

  for your own checks. The reader needs to know what to re-run.
• Mark a criterion Clean when it was checked and nothing came back. Mark it Not checked when no check ran. These are different things — never present the second as the first. Both are section-level statuses: write them as a line under the section heading, never as a row in the findings table with "Clean" in the Severity column. A findings table holds findings; a section with none has no table.
• Use the same table for every section. Do not switch between tables and loose

  Severity:

  /

  Finding:

  blocks partway through the report — one format throughout, so the reader can scan it.
• All six sections appear, always. A section with no findings carries a one-line status — Clean, or Not checked with the reason — never a bare heading with nothing under it. An empty section reads as an oversight, and the reader cannot tell whether it passed or was skipped.
• Name each companion exactly as the dispatch table does, every time it appears.

  docs-flag-jargon-skill

  and

  docs-flag-jargon

  are not two sources.
• A clean PR is a valid result. Never pad the report with trivia to look thorough. If a criterion produced nothing worth the author's time, it is Clean and you move on. A short report on a good PR is the correct output, not a sign you missed something.

select

click

• Approve — meets the quality threshold. Minor optional suggestions go in as comments rather than blocking.
• Comment — you have questions or non-blocking feedback.
• Request changes — below the quality threshold, or the change prevents users from succeeding with the product or feature. Blocking is a normal part of maintaining quality, not a judgment on the author.

This is a first pass, not a substitute for review. AI-generated results are not always accurate — confirm findings before acting on them.