docs-review-pr

Elastic ドキュメントのプルリクエストを、ドキュメントチームのレビュー用チェックリストに照らして確認します。6 つのレビュー基準（ユーザー重視、技術的な正確性、適用性、保守性、言語、スタイル）すべてを網羅した統合レポートを作成し、承認、コメント、変更依頼のいずれを推奨するかを示します。

これはオーケストレーターです。カタログには、スタイル、タグ付け、コンテンツタイプ、矛盾、メタデータ、コードサンプルを確認するスキルがすでにあります。それらに処理を委任し、結果をチェックリストの形式にまとめます。各スキルの評価基準を再実装してはいけません。

このスキルでは、意図的に context: fork を省略しています。カタログ内のほとんどのスキルでは設定されていますが、コンパニオンスキルを Skill ツールと Agent ツール経由で呼び出し、ステップ 1 で gh pr checkout についてユーザーに確認するため、メインコンテキストで実行する必要があります。各コンパニオンはそれぞれ自身でフォークするため、その出力は引き続きコンテキストに含まれません。

このスキルでは、常に完全なレビューを実施します。 簡易モードや軽微な変更向けのモードはありません。レポートのどの部分に対応するかを判断するのはレビュー担当者です。あなたの役割は、全体像を漏れなく提示することです。

制約

このスキルは読み取り専用です。

• ファイルを編集してはいけません。スクラッチパッド以外にファイルを書き込んではいけません。
• GitHub に投稿してはいけません。gh pr review、gh pr comment、gh pr merge を実行してはいけません。
• すべてのコンパニオンスキルをレポートのみのモードで呼び出し、この制約が間接的にも守られるようにしてください。書き込みを許可すると、2 つのコンパニオンがファイルを書き込む可能性があります。docs-applies-to-tagging は Edit を宣言しており、その検証モードでは報告または修正を行います。また、docs-validate-code-samples は Write を宣言しており、出力ファイルを書き込むことができます。どちらもサブエージェント経由でのみ呼び出し、書き込みを禁止する指示を起動プロンプトに含めてください。詳しくはステップ 3 を参照してください。
• 唯一の例外はステップ 1 の gh pr checkout です。実行を提案することはできますが、ユーザーが許可しない限り、決して実行してはいけません。

入力

$ARGUMENTS は、PR 番号、GitHub PR URL、ファイル、またはディレクトリです。空の場合は、現在のブランチをベースブランチと比較してレビューします。

ステップ 0：評価基準を読み込む

必ず references/review-criteria.md を読み込んでください（このファイルと同じ場所にあります）。これが評価基準です。ネットワーク、MCP、認証がなくても利用できるため、エージェント型のワークフローや CI に適しています。

次に、elastic-internal-docs MCP に接続できる場合は、get_internal_document_by_url と includeBody: true を使い、以下の正式なページから最新情報を取得してください。

ページ	URL
ドキュメントレビュー用チェックリスト	/r/docs-content-internal/processes/docs-review-checklists
PR レビューガイドライン	/r/docs-content-internal/processes/pr-reviews

取得したページの内容が評価基準と異なる場合は、そのページを優先してください。相違点があれば、レポートに記載してください。MCP に接続できない場合や認証されていない場合は、参照ファイルだけで十分です。その場合は、評価基準が更新されていないことが読者に分かるよう、レポートのヘッダーに Rubric source: references/review-criteria.md (MCP not reachable) と記載してください。

ステップ 1：対象を特定する

$ARGUMENTS	特定方法
PR 番号または GitHub PR URL	gh pr view <n> --json number,title,body,author,labels,files,baseRefName,baseRefOid,headRefName,headRefOid,headRepository,isCrossRepository,url と gh pr diff <n> を実行します。
空	現在のブランチを、そこから派生したブランチと比較します。まず、ブランチにすでに PR があるか確認します。PR が存在する場合は、番号を指定せずに gh pr view を実行すると対象を解決できます。PR が存在する場合はその PR を使い、PR 専用チェックを実行します。PR がない場合に限り、それらのチェックを省略します。
ファイルまたはディレクトリのパス	そこにあるファイルをレビュー対象として扱います。差分がないため、すべての行がレビュー対象です。新規追加部分と既存部分を区別できないため、ステップ 5 では推測せず、その旨を記載してください。PR 専用チェックは省略します。

レポートのヘッダーには、使用した入力モードと、PR メタデータを取得できたかどうかを記載してください。ブランチにオープン中の PR がある場合は完全なレビューを実施します。PR がないブランチとパス入力では、PR 専用チェックを省略します。読者がその違いを把握できるようにしてください。

すべてのモードでベースを解決する

このステップでは削除されたページを読み取る際に、またステップ 5 では検出事項の範囲を絞る際に、$BASE と $BASE_REPO を使用します。どのモードでも、対象の解決時にこれらを設定してください。ブランチレビューだけで設定するのではありません。PR レビューで、これらが未設定のまま削除されたページの読み取りに進むと、git fetch "https://github.com/.git" "" が実行され、わかりにくいエラーが発生します。

PR モード — PR 自体から両方の値を取得します。gh pr view には baseRepository フィールドがないため、ベースリポジトリは PR の URL から取得します。

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')

ブランチモード — GitHub にブランチのマージ先を問い合わせ、リポジトリのデフォルトにフォールバックします。アップストリーム追跡ブランチ（@{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

パスモード — 差分もベースもありません。両方とも未設定のままにし、それらを必要とするすべてのステップを省略して、該当するチェックには 未チェック — 比較対象のベースがありません と記してください。

これらの手順では、次の 2 点に注意しています。

• 番号を指定しない gh pr view は、現在のブランチに PR があればその PR を解決します。ブランチのマージ先について最も信頼できる情報です。成功した場合、そのブランチには PR があります。PR 専用のチェックを省略したと報告するのではなく、その PR のメタデータをラベル、作成者、本文に再利用してください。
• ベースブランチは origin ではなく、ベースリポジトリから取得してください。 フォークのクローンでは origin はフォークを指すため、origin/main はコントリビューター側の main のコピーであり、古いか、存在しない可能性があります。これと比較すると、変更されたファイルの一覧が誤ったものになります。URL を指定して FETCH_HEAD にフェッチすれば、ローカルのリモートが何を指しているかを気にせずに済みます。

差分が空だった場合は、クリーンなレビューを報告するのではなく、そこで停止してその旨を伝えてください。 空の差分は、レビュー対象が何もないのではなく、ほとんどの場合、ベースの解決が誤っていることを意味します。

作業ツリーが PR と一致していることを確認する

ファイルを読む前に実行してください。ステップ 4 のいくつかのチェック（孤立した画像、リダイレクトの欠落、親ページからの相互参照）では、ローカルリポジトリを grep します。PR の head ref がここでチェックアウトされていない場合、それらの grep は別のツリーを読み取り、誤った結果を自信満々に報告することになります。

ブランチ名ではなく、コミットを比較してください。ローカルブランチは PR の head と同じ名前でも、まったく別の場所を指していることがあります。そのため、次の手順を実行します。

1. git rev-parse HEAD が headRefOid と一致している必要があります。この確認ひとつでブランチ名、フォーク、古さをまとめて確認できます。コミットが一致すれば、ツリーも一致しています。
2. 一致しない場合は、何よりも先に正しいリポジトリにいることを確認してください。gh repo view --json nameWithOwner の結果を、PR のベースリポジトリ（PR URL 内の owner/name）と比較します。リモート URL の文字列ではなく、必ず owner/name で比較してください。同じリポジトリでも SSH 形式と HTTPS 形式では文字列が異なるためです。

ローカルリポジトリと headRepository を比較してはいけません。 フォークからの PR（isCrossRepository: true）では、head リポジトリはコントリビューターのフォークであり、誰もチェックアウトしていません。フォークからの PR はベースリポジトリをクローンしてレビューします。gh pr checkout はフォークの head を取得し、そこにローカルブランチを作成します。headRepository と比較すると、あらゆるフォーク PR を誤ったリポジトリとして拒否することになります。最も慎重なレビューを必要とするコントリビューションこそ、まさにその対象です。

• コミットが一致する — 続行します。

• Git リポジトリではない、または PR のベースリポジトリではない — 中止します。どのリポジトリから実行すべきかをユーザーに伝えます。

• 正しいリポジトリだが、ref が異なる — まず git status --porcelain --untracked-files=no で未コミットの作業を確認します。切り替えを妨げるのは追跡対象の変更だけです。変更がある場合は、チェックアウトを提案せず、stash またはコミットするようユーザーに伝えます。未追跡ファイルは妨げになりません。gh pr checkout はそれらに手を加えないためです。未追跡ファイルについて伝えたうえで続行します。妨げるものが何もない場合は、gh pr checkout <n> を実行するか尋ね、回答を待ちます。許可なくチェックアウトしてはいけません。

• ユーザーがチェックアウトを拒否した — 制限付きモードで続行します。変更された各ファイルを、リポジトリ相対の構造を保って、それぞれ個別のスクラッチパッドパスに書き込み、そのコピーをレビューします。

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

  最初の fetch の前に $SCRATCH を作成し、そのパスを報告してください。そうすれば、ユーザーはレビュー対象を確認できます。

  ファイルにリダイレクトすることが重要です。stdout にデコード済みの内容を出力しても、後続の Read、Grep、関連作業の各ステップで開けるものはありません。関連作業はスクラッチパッドのパスに対して実行します。ステップ 4 のリポジトリ衛生チェックはすべて、残りのリポジトリが引き続き誤ったコミットのままであるため、未確認 — 別の ref に対して実行と記載してください。問題なしと報告してはいけません。

変更されたファイルを読む

変更された各 .md ファイルを、差分の該当箇所だけでなく、最初から最後まで読んでください。H1 の正確さ、注意書きの積み重ね、コンテンツの配置、見出し構造はいずれもページ全体に関わるもので、差分の該当箇所だけでは把握できません。

削除・名前変更されたページには、ベース版が必要です。 head ref をチェックアウトすると、削除されたページや名前変更前のページはディスク上からなくなります。これらは、孤立アセットの確認とリダイレクトの確認に欠かせないファイルです。ベース版から読み取ってください。

通常、ベースコミットはローカルクローンにないため、読み取る前にフェッチしてください。フェッチしないと git show が bad-object エラーで失敗します。

git fetch "https://github.com/$BASE_REPO.git" "$BASE"
git show "$(git merge-base HEAD FETCH_HEAD)":<path>

フェッチできない場合（浅いクローンの場合や、ベースリポジトリにアクセスできない場合）は、gh pr view の出力にある baseRefOid を使って、代わりに API 経由でファイルを読み取ってください。

gh api "repos/{owner}/{repo}/contents/<path>?ref=<baseRefOid>" --jq .content | base64 -d

どちらの方法も使えない場合は、孤立アセットの確認とリダイレクトの確認を 未確認 — ベース版を利用できません と記録してください。削除されたページの内容を推測してはいけません。

差分に含まれる Markdown 以外のファイルも読んでください。 ナビゲーションファイル（toc.yml、docset.yml）とリダイレクトファイルも変更の一部であり、ページがビルドされ、引き続きアクセス可能かどうかを左右します。6 つの評価基準が文章を対象としていても、これらのファイルは確認対象です。

差分で実際に変更された行を記録してください。PR の場合は gh pr diff <n>、ブランチの場合は git diff -U0 <base>...HEAD を使います。名前だけの一覧では不十分です。ステップ 5 では、PR によって追加された箇所と、変更のない隣接箇所を区別するために行範囲が必要です。ファイルまたはディレクトリが入力された場合、差分は存在しないため、すべての行を対象として扱い、どの行が新しいか推測するのではなく、その旨をレポートに記載してください。

ステップ 2：作成者の情報を記録する

PR レビューガイドラインに従ってください。これは重点の置き方に影響しますが、確認の深さには影響しません。いずれの場合も、チェックリスト全体を実行してください。

作成者	確認の重点
開発者	通常、技術的な情報は正確だとみなして問題ありません。言語とスタイルを重視してください。
ライター（開発者がタグ付けされている場合）	技術レビューが保留中で、大幅な変更が加わった後に再レビューが必要になる可能性があることを記録してください。
ライターでも開発者でもない人（たとえば、顧客対応チーム）	誤字の修正以外については、対象分野の専門知識を持つライターが担当すべきこと、技術レビュー担当者も必要となる可能性があることを指摘してください。

gh pr view で分かるのは GitHub ログイン名であり、役割ではありません。作成者の種類は、確認できるチームへの所属、PR の説明、作成者が通常変更するリポジトリなど、確かな根拠がある場合にのみ推定してください。根拠が乏しい場合は 作成者の情報：不明 と記録し、重点の置き方に反映しないでください。作成者の種類をでっち上げると、レビュー全体の重点が知らないうちに変わってしまいます。

これをレポートのヘッダーに 1 行で記録してください。

ステップ 3：補助スキルをディスパッチする

Gate の条件を満たす補助スキルは、レビューのたびにすべて実行します。補助スキルが実行されないティアはありません。コードサンプルのバリデーターはコードブロックのない PR について指摘することがなく、タグ付けスキルは applies_to にまったく触れない差分について指摘することがないため、2 つの Gate は条件付きです。ディスパッチする前に Gate 列を確認してください。適用されない PR では、Gate 条件付きの補助スキルを実行しないでください。

#	補助スキル	ディスパッチ	Gate	指摘の報告先
1	docs-check-style	どちらでも	常時	言語、スタイル
2	docs-flag-jargon-skill	どちらでも	常時	言語
3	docs-content-type-checker	どちらでも	常時	ユーザーの焦点
4	docs-check-contradictions	どちらでも	常時	技術的な正確性
5	docs-frontmatter-audit	どちらでも	常時	ユーザーの焦点
6	docs-applies-to-tagging	サブエージェントのみ	差分が applies_to またはバージョンに紐づくコンテンツに触れる場合	適用可能性
7	docs-validate-code-samples	サブエージェントのみ	差分がコードブロックを追加または変更する場合	技術的な正確性

7 つの補助スキルは、それぞれ個別にディスパッチします。2 つを 1 回の呼び出しや 1 つのサブエージェントにまとめてはいけません。 最後の列は、補助スキルの指摘をどこに報告するかを示すものであり、グループ分けの基準ではありません。補助スキル 1 と 2 はどちらも「言語」に、3 と 5 はどちらも「ユーザーの焦点」に報告しますが、それぞれ独自の評価基準を持つ個別のディスパッチです。まとめると、2 つの評価基準のどちらかが実行されないままになり、実行記録の表では実際には行っていない確認まで済ませたことになってしまいます。

常時 Gate の補助スキル 5 つは、例外なくレビューのたびにディスパッチします。これらについて「ディスパッチしなかった」は有効な結果ではありません。 いずれかに到達できなかった場合は、「未インストール」または「応答なし」として、そのように報告します。

すべての補助スキルは、6 つのレポートセクションのいずれかに対応します。7 つ目のセクションが追加されることはありません。docs-frontmatter-audit の指摘は、見つけやすさとメタデータに関するものとして「ユーザーの焦点」に含めます。

ディスパッチ方法

コンパニオンはモデルから呼び出せるため、単独でインストールされている場合も、elastic-docs-skills プラグインの一部としてインストールされている場合も、Skill ツールから呼び出せます。例外は docs-validate-code-samples です。ファイルを書き込む可能性があるため、disable-model-invocation: true のままにしています。このコンパニオンは常にサブエージェント経由で実行され、ディスクから SKILL.md を読み込むため、このフラグの影響を受けません。

各コンパニオンの呼び出し先は Path 列で決まります。読み取り専用のコンパニオンはパス 1 を試し、失敗した場合はパス 2 に切り替えます。書き込み可能なコンパニオンは、最初からパス 2 を使います。各コンパニオンが実際に使ったパスを記録し、報告してください。

1. Skill ツール — Path 列で指定された読み取り専用のコンパニオンのみが対象です。レビューするファイルを 1 つ、args として渡します。README に記載されている形式である、プラグイン接頭辞付きの frontmatter 名 elastic-docs-skills:docs-content-type-checker を使ってください。接頭辞付きの名前が拒否された場合は、接頭辞なしの名前に切り替えます。.claude/skills/ の下にプロジェクトスキルとしてインストールされたコピーは、frontmatter の name ではなくディレクトリ名で応答するため、その形式は最後に試してください。

   Edit または Write を宣言しているコンパニオンは、このパスを使いません。 Skill の呼び出しで指定できるのは args だけです。検証だけを依頼しても、書き込みが行われない保証にはなりません。docs-applies-to-tagging はファイルパスを検証モードとして扱いますが、検証モードでも報告または修正が行われます。書き込みを実際に禁止できるのは、サブエージェントの起動プロンプトだけです。そのため、applies-to-tagging と docs-validate-code-samples は、Skill ツールで呼び出せる場合でも常にパス 2 を使います。

   呼び出し 1 回につき、変更ファイルは 1 つです。 コンパニオンは <file-or-directory> を受け取り、$ARGUMENTS に対して glob を実行します。そのため、スペースで区切った複数のパスは、複数の有効なパスではなく、1 つの無効なパスとして扱われます。変更ファイルごとに 1 回ずつ呼び出してください。ディレクトリを渡せるのは、変更対象だけが含まれ、それ以外のファイルがない場合に限ります。そうでないと、コンパニオンが無関係なページも glob し、その指摘が報告に混入して推奨内容に影響します。迷った場合は、呼び出し 1 回につきファイル 1 つにしてください。このルールは両方のディスパッチ方法に適用されます。

2. サブエージェント。 書き込み可能なコンパニオンで必須となる方法です。また、Skill の名前がどちらの形式でも拒否された場合、または登録されていない場合の代替方法でもあります。コンパニオンごとに 1 つのサブエージェントを起動し、すべてを 1 つのメッセージで指定して並列に実行します。各サブエージェントは次のとおりです。

   • ~/.claude/skills/*/SKILL.md、~/.claude/plugins/**/skills/**/SKILL.md、およびローカルリポジトリの skills/**/SKILL.md を glob してコンパニオンの SKILL.md を探し、ディレクトリ名または frontmatter の name: フィールドで照合します。
   • $ARGUMENTS を単一のパス（ファイル 1 つ、または共通の親ディレクトリ）に置き換え、パス 1 と同じ対象 1 つのルールに従って、変更ファイルに対して記載された指示をそのまま実行します。
   • 簡潔な指摘一覧を返します。各項目にはファイル、行、重大度、指摘を記載します。コンパニオンのレポート全体は返しません。

   コンパニオンから評価基準を読み込むことで、このスキルの内容を簡潔に保てます。コンパニオンのルールをこのファイルにコピーしないでください。

3. 未インストール。 コンパニオンが見つからない場合は、その評価項目を 未確認 — <skill> がインストールされていません と記載し、インストールコマンドを示してください。

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

   コンパニオンの frontmatter にある name: を使ってください。たとえば、check-contradictions ディレクトリではなく docs-check-contradictions を使います。インストールコマンドが受け取るのはこの名前です。呼び出し名は別の問題です。.claude/skills/ の下にプロジェクトスキルとしてインストールされたコピーは、ディレクトリ名で応答するため、コンパニオンを未インストールと報告する前に、その形式を試してください。

実行されなかったコンパニオンの代わりを決して務めないでください

これは、コンパニオンが何も出力しなかった理由が、未インストール、拒否、エラー、またはディスパッチ後に応答がなかった場合のすべてに当てはまります。

• そのコンパニオンの評価基準について、自分で指摘事項を書かないでください。また、その不足を手動評価として扱わないでください。自分で行う確認は Step 4 のリストにあるものであり、コンパニオンの評価基準の代わりにはなりません。コンパニオンが存在する理由は、まさにその評価基準を担うことです。
• 評価基準には 未確認 と記載し、どのコンパニオンが、なぜ未確認なのかを示して、それ以上は記載しないでください。手作業で補って確認済みのように見せた評価基準は、確認できなかったと認めた場合よりも問題です。レポートを見た人が、両者を区別できなくなるためです。
• 例外は、Step 4 に基づいて自分が実際に見つけた指摘事項です。その場合は docs-review-pr を出典として記載し、独立した行にしてください。応答のなかったコンパニオンの欄に決してまとめないでください。

レポートのみのモードは必須です

Skill の経路では、検証またはレビューのみを求める引数を渡してください。生成や修正は求めないでください。また、これは依頼であって強制ではないことを忘れないでください。そのため、書き込み可能なコンパニオンはこの経路から除外されています。サブエージェントの経路では、起動プロンプトに以下をそのまま記載してください。

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

レポートを作成する前に、すべてのコンパニオンの応答を待つ

どちらのディスパッチ経路も、処理を分岐させてバックグラウンドで実行します。結果は、呼び出しの戻り値ではなく通知として届きます。

• ディスパッチしたすべてのコンパニオンから応答があるまで、Step 5 を開始しないでください。
• 応答待ちのコンパニオンが何を言うか、予測、要約、捏造しないでください。コンパニオンの出力をでっち上げることは、このスキルで最も重大な失敗です。レポートの形式上、出典が明記され、検証済みであるかのように見えてしまうためです。
• コンパニオンでエラーが発生した場合、または応答がない場合は、その評価基準に 未確認 — コンパニオンから応答なし と記載し、残りの作業を続けてください。自分の評価で不足を補わないでください。詳しくは 実行されなかったコンパニオンの代わりを決して務めないでください を参照してください。

レポートを作成する前に、件数を確認してください。 実行表には、ディスパッチ表のコンパニオンごとに 1 行、合計で必ず 7 行を記載してください。常時実行対象のコンパニオンはすべて、実行済み、未インストール、または 応答なし のいずれかでなければなりません。未ディスパッチ としてはいけません。ある行にスキップしたと記載されている場合は、ディスパッチを忘れたか、別の呼び出しにまとめたということです。戻ってディスパッチしてください。

Step 4: どのコンパニオンも扱わない確認を実施する

これは、レビューにおけるあなた自身の貢献です。すべての指摘事項の対象を、PR で変更された内容に限定してください。

ユーザーの視点

• 変更がユーザーのタスクに役立ち、ページ上の適切な場所に配置されていること。
• 段落が短く、リスト、表、注記によって密度の高い内容が分割されていること。
• 導入文でトピックの範囲が明確になり、続く内容をどう捉えるべきかが読者に伝わること。
• 機能や手順の仕組みだけでなく、そのメリットが明示されていること。次の 3 か所で確認してください。導入部／説明（仕組みだけでなく、ユーザーにとってのメリット）、各判断箇所（両方の選択肢の説明だけでなく、トレードオフ）、タイトル（ページの内容がタイトルの約束を果たしているか）。
• 新たに導入した概念を使用するリファレンスページを含め、影響を受けるすべてのページが評価され、更新されていること。
• 新機能が、製品全体における位置づけを踏まえて親ページで説明されていること。
• ページのフロントマターで、type: によってコンテンツの種類が宣言されていること。 docs-content-type-checker がページをハウツー、チュートリアル、概要、またはトラブルシューティングのページと判定し、フロントマターに type: フィールドがない場合は、追加を推奨し、適切な種類を指定してください。新規ページだけでなく、編集したページにも適用してください。既存ページはテンプレートを経ていないため、このフィールドが欠けていることが最も多いためです。まだこのフィールドを利用するものがなくても、追加を推奨してください。コンテンツの種類を表すタグがないことを指摘する構造上の指摘では、すでに判断した内容を読者に推測させることになります。

見つけやすさと論理的な流れ

• ページが情報アーキテクチャ内の適切な場所にあります。
• 親ページからこのページへの相互参照があり、ユーザーが行き詰まらないようになっています。リポジトリ内を検索し、新規ページまたは移動したページへのリンクを探します。
• 見出しは、可能であれば50～60文字程度で、類似するページとの違いが明確に分かる内容になっています。
• 情報は段階的に示され、読者が必要な情報を必要な順序で得られます。
• 警告や注意事項は、それが対象とする手順や内容の後ではなく、前に記載されています。
• 概念上の選択肢は対比して示され、選択肢の利点は判断する箇所の近くに記載され、分岐する判断には階層化されたナビゲーションが使われています。
• 既存のページで同じ内容がすでに扱われていません。ページのトピックについて、elastic-docs MCP ツールの find_related_docs で確認します。

技術的な正確性を示す根拠

SME が変更をレビューしたかどうかを確認することはできません。根拠があるかどうかは報告できます。

• PR 本文、レビューコメント、ブランチ名、リンク先の Issue を確認し、SME の承認、エンジニアリングレビュー、または信頼できる情報源があるかを調べます。
• 新しいコードサンプルに、テスト済みであるとの説明があるか確認します。
• 根拠がある場合はその内容と場所を、ない場合は根拠がないことを明確に述べます。自信に満ちた文章から技術的な正しさを推測してはいけません。

ドキュメントと説明対象のコード変更を照合する

その根拠がコード PR またはコミット（elastic/elasticsearch#12345、GitHub PR の URL、「Docs for kibana#678」、Issue にちなんだブランチ名など）の場合、存在を記録するだけで終わらせず、その内容を読み、照合してください。リンクされたコード変更からリポジトリ、ref、バージョンを特定できるため、信頼すべき情報源を推測せずに行える唯一の技術的な確認です。コード変更への言及がない場合は、このブロック全体を省略してください。確認のためにコード変更を探しに行ってはいけません。

1. 参照先を特定し、両方の内容を読みます。

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

   番号を --repo と一緒に渡すか、完全な PR URL を指定します。省略形式の gh pr view elastic/elasticsearch#12345 は機能しません。gh はこれをブランチ名として扱って PR が見つからないと報告するため、コマンドの誤りではなく PR が存在しないように見えてしまいます。

2. コード差分から確認できる事実を抜き出します。設定、フラグ、パラメーターの名前、デフォルト値、上限、列挙値、エラーおよびログメッセージの文言、追加または変更されたテストを確認します。意図された動作を示すうえでは、コメントの説明よりもテストの方が信頼できます。

3. それぞれをドキュメントの変更内容と照合します。コード PR と差分内のファイルを示しながら「技術的な正確性」の項目で報告し、執筆者が同じ手順をたどれるようにします。

自信を持って誤った判断をしないために、次の4点を正しく確認してください。

• バージョン。 コード PR の baseRefName から、マージ先のブランチが分かります。ページの applies_to と照合してください。9.2 向けのドキュメントが 8.19 に取り込まれた変更について説明している場合、これは実際の指摘事項であり、このレビューの他の確認では見つけられません。
• マージ状況。 未マージのコード PR が示すのは、今後変更される可能性がある動作です。確定事項として扱わず、その旨を述べてください。
• 記載がないことは何も証明しません。 ドキュメントの記述がコード差分にないからといって、それが誤りとは限りません。差分は1つの変更であり、製品全体ではありません。直接矛盾している場合にのみ指摘してください。たとえば、ドキュメントではある値を示し、コードでは別の値を示している場合です。
• 一致しても検証にはなりません。 何がどこで一致したのかを報告してください。差分と一致したことを根拠に、変更が技術的に正しいと書いてはいけません。自信に満ちた文章に適用されるのと同じ原則が、自信に満ちた差分にも適用されます。

タグ付けスキル以外の適用性チェック

• 変更後も、権限、セットアップ、前提知識を含む前提条件が正確です。
• 新たに必要になった権限やセットアップの依存関係が、明記されないまま残っていません。
• デプロイの種類やバージョンがページレベルのタグ付けと異なる場合は、前提条件に明記されています。
• デプロイ範囲が適切です。該当する種類を網羅するか、その情報への案内があり、共通プロセスはデプロイの種類に依存せず、セルフマネージド、ECE、ECKは、顧客が運用する単一のグループにまとめず、それぞれ異なるデプロイの種類として扱われています。これらは中核となる Elasticsearch の機能を共有しています。違いはデプロイの運用方法であり、実行できることではありません。

保守性とリポジトリの整理

• すでに別の場所にある手順や値を重複して記載していません。相互参照やスニペットのほうが適切です。セクションに参考情報（パラメーターの説明、形式の説明、API 構文、手順全体）が含まれている場合は、find_related_docs または search_docs を使って、専用ページですでに説明されていないか確認します。ページ内の重複も確認します。オプション 1 とオプション 2、または方法 A と方法 B を並べて読みます。
• 削除または移動したページの古いパスを指すリンクや参照が、ページに残っていません。リポジトリ全体を対象に、古いパスとアンカーを grep します。
• 削除した画像やスニペットを参照するページが残っていません。削除したアセットのパスごとに、リポジトリ全体を grep します。
• 名前変更、移動、削除したすべてのページに、対応するリダイレクトエントリーがあります。名前変更したアンカーも含みます。欠落はライブリンクを壊すため、重大として報告します。ファイルは、コンテンツセットの docset.yml または _docset.yml と同じ場所にある redirects.yml または _redirects.yml です。欠落を報告する前に両方のファイル名を確認します。そうしないと、誤検出につながります。
• 生成された資料や自動生成される参考情報を手作業で編集していません。修正はソースで行います。
• スクリーンショット、図、Elastic 以外の外部リンクは、継続的な保守コストに見合っています。

スコープの規律

• 変更でロードマップ項目や将来の計画を約束していません。
• 変更に、ユーザーに不要な実装の詳細や意思決定の経緯が含まれていません。

プレビューの整合性

• リテラルの {{ がレンダリング結果に残らず、すべての置換が解決されています。
• 警告ブロックが連続していません。1つの注記にまとめるか、本文に含めます。連続する組み合わせを確認します。空白だけを挟んだ2つの警告ブロックは、個別には問題がなくても連続とみなされます。
• 1つの領域にある警告ブロックは、おおむね3つ以下で、目立つ状態が保たれています。
• 余分な箇条書き、残ったコメント、壊れた表やタブセットがありません。
• バッジが正しくレンダリングされ、セクション単位または行単位の applies_to タグがページレベルのタグと併用できます。
• リンクテキストに意味があり、新規または変更したリンクが解決されます。

PR の手続き

入力がパスで、PR ではない場合は、このブロックをスキップします。

• バックポート用ラベルがあり、対象ブランチに対して正しく設定されています。gh pr view --json labels で確認します。
• 未完了のコンテンツが残っていません。TODO、プレースホルダーテキスト、コメントアウトされた下書きなどが該当します。
• 変更後もタイトルと H1 が正確で、文として適切な大文字・小文字表記になっています。

ステップ 5：マージして報告する

チェックリストの順番に沿って、6つの基準ごとにセクションを分けた1つのレポートを作成します。

ヘッダー

Target: <PR #, title, URL — or branch/path>
Author signal: <author type → where you focused>
Rubric source: internal MCP | embedded fallback — <reason>
Working tree: head ref checked out | degraded — <what was skipped>

続けて、各スキルについて、実行されたかどうかと実行経路を記載した一覧表を示します。スキップした場合は（該当しない理由を添えて）スキップと記載し、インストールされていない場合はその旨を記載します。

Findings

基準ごとにまとめます：ユーザーへの焦点、技術的な正確性、適用可能性、保守性、言語、スタイル。各項目につき、指摘は1行で記載します。

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

• 重大度 — ページに従ったユーザーが失敗したり、誤解したりする場合、または有効なリンクが壊れている場合は「高」とします。内容に一貫性がない、または不明瞭でも利用は可能な場合は「中」とします。細かなニュアンスは「低」とします。
• ガイドライン — references/review-criteria.md のルール引用表から、指摘の根拠となるルールへのリンクを記載します。表にセクションのアンカーがある場合はそれを、ない場合は該当基準を規定するページへのリンクを記載します。指摘が実際に基づいているルールを引用し、たまたま該当項目が置かれているセクションのルールを引用しないでください。description の欠落はメタデータと見つけやすさに関するルールであり、seo#headings ではありません。不明瞭なトリガー条件は明確さの問題であり、grammar-spelling ではありません。「Technical accuracy」のような基準名は引用ではありません。指摘を分類する場所の名前であって、根拠となるルールではありません。表に該当するものがなければ、近そうなリンクを無理に選ばず、列を空欄にしてください。誤った引用は、主張の根拠になっていないルールへ執筆者を誘導してしまいます。この列に記載できるのはリンクまたは空欄のみです。findability のような単語だけの記載や基準名は引用ではないため、記載してはいけません。Language と Style の指摘には、すべて引用を付けてください。 また、特定のページが判断基準となる他の指摘にも引用が必要です。異議がある執筆者が確認できる場所を用意してください。「スタイルガイドにそう書いてある」だけでは引用になりません。Vale のルールである Elastic.OxfordComma のように、関連するスキルが独自のルール名を報告している場合は、それも含めて、どのチェックに該当したのか執筆者にわかるようにしてください。アンカーを捏造してはいけません。該当する項目が記載されていない場合は、ページを引用し、どの部分が適用されるのかを説明してください。
• Source — どの関連スキルが指摘を出したのか、または独自のチェックの場合は docs-review-pr を記載します。読者が何を再実行すればよいかがわかるようにしてください。
• 基準を確認した結果、問題がなかった場合は Clean とします。チェックを実行していない場合は Not checked とします。この2つは異なる状態です。後者を前者として示してはいけません。どちらもセクション単位のステータスです。指摘テーブルの重大度欄に「Clean」と記載するのではなく、セクション見出しの下に1行で記載してください。指摘テーブルには指摘を記載します。指摘がなければテーブルは作成しません。
• すべてのセクションで同じテーブルを使用してください。レポートの途中でテーブルと、形式の異なる Severity:／Finding: ブロックを切り替えてはいけません。読者が確認しやすいよう、全体を通して同じ形式にします。
• 6つのセクションは必ずすべて記載します。 指摘のないセクションにも、Clean、または理由を添えた Not checked のいずれかを1行で記載してください。見出しだけで内容のないセクションにしてはいけません。空のセクションでは、確認漏れなのか、チェックを省略したのかが読者にわかりません。
• 関連スキル名は、記載するたびにディスパッチテーブルの表記と完全に一致させてください。docs-flag-jargon-skill と docs-flag-jargon は、別々のソースではありません。
• 問題のない PR も正当な結果です。 入念さを装うために、些細な指摘を加えてはいけません。執筆者の時間を使う価値のある指摘がない基準は Clean とし、次に進みます。良好な PR に対する短いレポートは、見落としの兆候ではなく、適切な結果です。

繰り返し発生するパターン

PR 全体で同じ問題が繰り返されている場合は、件数と例を2つほど添えて、パターンとして1回だけ報告します。PR レビューのガイドラインにあるレビューのエチケットに従い、すべての箇所にコメントするより、全体を対象にしたコメントを1つ記載するほうが適切です。

既存の問題

この PR で生じたものではない問題に気づいた場合は、独立したセクションに、既存の問題であることが明確にわかるよう記載します。無関係な技術的負債の責任は執筆者にはありません。既存の問題と混在させると、レビューが恣意的に見えてしまいます。

このセクションに記載するのは問題であり、称賛ではありません。PR による優れた改善は What is working に記載してください。ここに記載すると、その改善が既存の欠陥だったと執筆者に伝わってしまいます。既存の問題がなければ、その旨を1行で記載します。

うまくできている点

内容の優れた箇所があれば、簡潔かつ具体的に伝えてください。肯定的なフィードバックは、良い文章を書く習慣を後押しし、レビューの心理的な負担を和らげます。

推奨する対応

上記の指摘をもとにこのリストを作成し、記憶を頼りにしてはいけません。 各アクション項目では、すでに記載した指摘を、同じ方向性で言い換えてください。要約時に修正内容を改めて考えてはいけません。そうすると、報告書の指摘では逆の内容が述べられているのに、作成者に select を click に変更するよう勧めることになり、しかも要約は人々が実際に行動に移す部分です。項目を書く前に、元となる指摘を読み返し、方向性が一致していることを確認してください。対応する指摘が上にない項目は、リストに含めるべきではないか、報告書に指摘が欠けています。

理由を添えて、Approve、Comment、Request changes のいずれかを選択してください。

• Approve — 品質基準を満たしています。軽微な任意の提案は、ブロックせずコメントとして記載してください。
• Comment — 質問がある、またはブロック対象ではないフィードバックがあります。
• Request changes — 品質基準を満たしていないか、変更によってユーザーが製品や機能を使えなくなります。品質を維持するうえでブロックするのは通常のことであり、作成者への評価ではありません。

最後に添える注意書き

レポートがレビューそのものとして扱われないよう、最後に次の文を添えてください。

これは初回の確認であり、レビューに代わるものではありません。AI が生成した結果は必ずしも正確ではないため、対応する前に指摘内容を確認してください。