docs-check-contradictions

Elastic のドキュメントの一貫性を確認します。役割は、既存のドキュメント内で、新規または更新されたコンテンツと矛盾・衝突する箇所を見つけることです。内容を書き換えてはいけません。変更とあわせてほかに更新が必要な箇所を執筆者が判断できるよう、見つかった問題を報告します。

このチェックは、ドキュメントのあらゆる編集に対応します。新しい機能ページ、手順の改訂、概念の説明の更新、前提条件の変更、設定名の変更、値の修正、新しい推奨事項などが対象です。変更が機能に関するものだと決めつけないでください。

このスキルは、文章や書式を確認する docs-check-style と、デプロイ範囲のタグを確認する docs-applies-to-tagging を補完するものです。新しいコンテンツの記述と、ほかのドキュメントの記述との間にある事実の矛盾だけに注目してください。

Elastic のドキュメントは複数のリポジトリ（コードリポジトリを含む）に分散しているため、矛盾が、チェックアウトされていないリポジトリに存在することもよくあります。そのため、次の2か所を検索します。

1. ローカルのチェックアウト（Grep／Glob を使用）— 編集対象のリポジトリ内にある矛盾を検出します。まだ公開されていない作業中のコンテンツも対象です。
2. 公開済みのすべての Elastic ドキュメント（認証不要の Elastic Docs MCP サーバー https://www.elastic.co/docs/_mcp/ を使用）— ローカルにチェックアウトする必要なく、公開済みの全リポジトリにわたる矛盾を検出します。

Elastic Docs MCP サーバーのツール（search_docs、get_document_by_url など）がこのセッションで利用できない場合は、特定の公開済みドキュメント URL に対して WebFetch を使用してください。レポートでは、どちらの方法を使ったかを明記してください。MCP が確認できるのは公開済みのドキュメントだけです。別のリポジトリにある未マージまたは未公開の変更との矛盾は検出されないため、リポジトリをまたいだチェックの対象は公開済みコンテンツに限られることをレポートに記載し、執筆者に知らせてください。

入力

$ARGUMENTS は、新規または更新されたドキュメントを含むファイルまたはディレクトリです。空の場合は、チェック対象のファイルまたはディレクトリをユーザーに尋ねてください。

手順 1：新しいコンテンツを読む

$ARGUMENTS 内のすべての .md ファイルを Glob で検索します。各ファイルを最後まで読みます。

読みながら、事実に関する主張のリストを作成します。新しいコンテンツに記載された主張を正確な文言で記録し、ファイルパスとおおよその行番号も記載します。手順、概念ページ、リファレンステーブル、前提条件の注記、推奨事項など、どのようなコンテンツでも主張が含まれる可能性があります。次の種類の主張を探してください。

主張の種類	例
値	デフォルト値、しきい値、タイムアウト、制限、最大値、ポート、パス、件数
名称	設定、API フィールド、CLI フラグ、UI 要素、ファイル、ロール、製品機能の正確な名称
手順と操作手順	手順の順序、最初に行う操作、UI 内で設定がある場所、ページへの移動方法
前提条件と要件	必要なバージョン、ライセンス、権限、依存関係、事前に必要な設定
概念と定義	用語の意味、概念の説明、あるものが何であるか、または何でないか
利用可能性と範囲	対象となるデプロイタイプとバージョン範囲（serverless、ECE、ECH、セルフマネージド、バージョン範囲）
関係性	「X には Y が必要」、「X は Y に置き換わる」、「X は Z を優先して非推奨になる」、「X は削除される」、「Y の代わりに X を使用する」
機能	「X は Y をサポートする」、「X は Y をサポートしない」、「X は Z では利用できない」
推奨事項	推奨されるデフォルト値、ベストプラクティスの指針、ほかのページと両立しない「X を推奨します」などの記述

事実に基づく矛盾が生じない、純粋に主観的な説明文は除外してください。別のページで反証される可能性のある主張だけを集めます。

ステップ 2：検索語を作成する

主張の一覧から、検索に使う最も具体的な用語を抽出します。

• 正確な設定名、API パラメーター名、CLI フラグ名
• 機能名や製品コンポーネント名
• 複数の場所に登場する具体的な値（バージョン番号、デフォルト値）
• 別の場所で同じトピックを特定できる、十分に固有な語句

置換変数：Elastic のドキュメントでは、{{motlp}}、{{edot}}、{{agent}}、{{ech}} のような変数が使われています。主張に置換変数がある製品や機能が関係する場合は、表示名（例：「Managed OTLP Endpoint」）と置換変数（例：motlp）の両方を検索します。同じ主張が、公開済みドキュメントでは表示テキストとして、ローカルのソースファイルでは変数として現れる場合があります。

一般的な単語 1 つよりも、具体的な複数語の用語を優先します。これらの用語は、ローカル検索とリポジトリ横断検索の両方で再利用します。

ステップ 3a：ローカルのチェックアウトを検索する

各検索語について、Grep を使って、同じトピックに言及している $ARGUMENTS 以外の .md ファイルを検索します。

Grep -r "<term>" --include="*.md" .

一致したファイルパスを収集します。ステップ 1 ですでに読んだファイルは除外します。また、次のものも除外します。

• _snippets/ ディレクトリ — スニペットの内容は、それを含めるページの文脈に沿って記述されています。スニペット内の矛盾は、取り込み元のページに現れます。
• release-notes/ — 意図的に履歴の正確性を保つものです。バージョン固有の主張を矛盾として指摘しないでください。
• redirects.yml — 説明文ではありません。
• 自動生成ファイル（例：nav.yml、toc.yml）

検索語に一致するファイルが多数ある場合は、次に進む前に、より具体的なサブタームに絞り込むか、$ARGUMENTS と同じ製品領域またはディレクトリにあるファイルを優先します。

ステップ 3b：公開済みの Elastic ドキュメントをすべて検索する（リポジトリ横断）

ローカルのチェックアウトは、多数あるリポジトリの 1 つにすぎません。ほかのリポジトリから公開されたドキュメントにある矛盾を見つけるには、Elastic Docs MCP サーバーのツールを使います。

重要な主張または用語ごとに、次の手順を実行します。

1. search_docs を用語とともに呼び出し、同じトピックの公開ページを探します（製品やセクションが分かっている場合は、フィルターを使います）。必要に応じて find_related_docs を呼び出し、検索範囲を広げます。これらは主な検索手段で、実際に比較する候補ページを見つけます。
2. トピックとの関連性が最も高い検索結果について、includeBody: true を指定して get_document_by_url を呼び出し、実際の内容を読みます。矛盾は検索メタデータではなく、内容を読んで比較することで見つかります。
3. 必要に応じて、主なトピックに対して find_docs_inconsistencies（および check_docs_coherence）を呼び出し、候補を追加します。出力は候補の発見のみに使用します。これらのツールが検出するのは、トピックが重複するページ（同じテーマを扱っており、冗長である可能性があるページ）であり、実際に内容が食い違うページではありません。返された候補はすべてステップ 4 で読み、主張の一覧と比較する必要があります。これらのツールの検索結果だけを根拠に、矛盾として報告しないでください。

MCP ツールが利用できない場合：特定の公開ドキュメント URL（例：https://www.elastic.co/docs/reference/opentelemetry/compatibility/limitations）に対して WebFetch を使います。レポートには、リポジトリ横断チェックで MCP ではなく WebFetch を使ったこと、および検索範囲が狭くなる可能性があることを記載してください。

編集中のファイルと同じページ（自分のページの公開版）はスキップします。ステップ 3a ですでに見つかったものと重複するページも除外します。

ステップ 4：読み比べる

各候補ページ（ローカルのページ（ステップ 3a）と公開ページ（ステップ 3b））の該当セクションを読み、記載内容を主張のリストと照らし合わせます。

• 同じ項目について、異なる値、上限、パス、名前が記載されていますか？
• 新しい内容と矛盾する手順、順序、手続きが説明されていますか？
• 異なる前提条件、要件、権限、バージョンが列挙されていますか？
• 用語や概念が、現在とは合わない形で定義されていますか？
• 変更された設定、パラメーター、機能名が使われていますか？
• 新しい内容とは反対に、何かが利用可能または利用不可だと記載されていますか？
• 同じイベント（導入、非推奨化、削除）について、異なるバージョンが示されていますか？
• 新しい推奨事項と両立しないことが推奨されていますか？
• 新しい内容に置き換えられた動作やガイダンスが説明されていますか？
• applies_to タグが、新しい内容の利用可能性に関する主張と矛盾していますか？たとえば、新しい内容ではプレビューとされている機能を、GA として示していますか？

実際の事実関係の矛盾のみを指摘します。表現、詳細度、ドキュメントのスタイルの違いは指摘しないでください。

ステップ 5：レポートを作成する

指摘事項を書く前に、各矛盾を評価します。

修正の方向性 — このスキルでは 2 つのドキュメント成果物を比較しますが、どちらが正しいかは確認できていません。どちらのページが正しいかを断定するのではなく、証拠がどちらを示しているかを明記し、執筆者と SME が最終判断できるようにします。

• Review draft — 複数の独立した既存ソースが一致している場合、または明示的な制限事項／警告の注記が新しい主張と直接矛盾している場合（強い根拠ですが、確認は必要です）
• Review existing — 新しい内容が意図的な更新であると思われる場合（たとえば、近くにあるバージョン注記や変更履歴の項目が、その変更が意図的であることを示している場合）
• Verify both — 具体的な値や主張が食い違っており、どちらが現在の製品の動作を反映しているかを判断する明確な根拠がない場合。どちらのページを更新する前にも SME に確認する必要があります

指摘事項は、執筆者が直接修正できる箇所と、別のリポジトリにある箇所がわかるよう、ローカルとリポジトリ横断のセクションに分けた構造化レポートとして提示します。矛盾ごとに、次の情報を記載します。

1. 場所 — ローカルファイルの場合は、クリック可能な Markdown リンクを記載します：path/to/other-file.md:42。公開ページの場合は、ドキュメントの URL を記載します。
2. 重要度 — High / Medium / Low
3. 方向性 — 次の 3 つの値のいずれかを厳密に使用します：Review draft / Review existing / Verify both。このフィールドにファイル名、補足、括弧書きを追加しないでください。補足は「推奨事項」フィールドに記載します。
4. 主張の種類 — 次のいずれかを使用します：Values、Naming、Steps/Procedure、Prerequisites、Concepts/Definitions、Availability/Scope、Relationships、Capabilities、Recommendations
5. 矛盾 — 既存の内容と新しい内容の記載事項を、短い場合は正確な引用を用いて説明します。
6. 推奨事項 — 想定される修正内容と修正箇所を示します。修正に着手する前に SME の確認が必要な場合は、必ずその旨を記載します。

レポート形式

## Contradiction check: <input file or directory>

### Summary
N contradictions found (X local, Y cross-repo) across M pages. Blockers: B.
Cross-repo check: ran via MCP / ran via WebFetch / skipped — <reason>.

### Local repo

#### [path/to/existing-file.md](path/to/existing-file.md)
- **[Line 42](path/to/existing-file.md#L42)** | High | Review existing | Values | Existing: "Requests time out after 30 seconds by default." New content sets the default at 60 seconds. → Confirm with an SME which value is current; update whichever page is wrong.
- **[Line 88](path/to/existing-file.md#L88)** | Medium | Review draft | Naming | Existing uses the current setting name `refresh_interval`. New content uses the old name `index.refresh_interval`. Multiple pages agree on `refresh_interval`. → Likely update the draft, but confirm the rename is complete.

### Cross-repo (published docs)

#### https://www.elastic.co/docs/<path>
- **Medium | Verify both | Prerequisites** | Published page requires a Platinum license; new content says the feature works on Basic. → Verify the correct tier with an SME and update whichever page is wrong.

矛盾が見つからなかった場合は、そのことを明確に伝えてください。全文を読み取るには大きすぎたためにスキップしたファイルがあれば、そのファイルを記載してください。また、クロスリポジトリチェックを実行したかどうか、実行した場合はその方法（MCP または WebFetch）を必ず記載してください。

最後に、1 行の要約を記載してください。「矛盾が N 件見つかりました（ローカル X 件、クロスリポジトリ Y 件）。重大度の高いものは B 件あります。マージ前に解決してください。」（問題がなければ「矛盾は見つかりませんでした。」）クロスリポジトリチェックの対象は公開済みのドキュメントに限られるため、他のリポジトリにある未公開の変更は含まれないことを執筆者に伝えてください。正しい状態が不明な指摘事項については、どちらかのページを変更する前に SME に確認する必要があると記載してください。