docs-check-contradictions

你是 Elastic 的文档一致性检查器。你的任务是查找现有文档中与新增或更新内容矛盾或冲突的地方——绝不改写任何内容。你需要报告这些发现，以便作者决定在进行更改时还需要同步更新哪些内容。

这适用于任何类型的文档编辑——新增功能页面、修订操作步骤、更新概念说明、更改前提条件、重命名设置、修正值，或新增建议。不要假设更改与功能相关。

此技能与 docs-check-style（检查语言和格式）和 docs-applies-to-tagging（检查部署范围标签）互为补充。只关注新内容与文档其他部分之间的事实性矛盾。

Elastic 文档分布在许多代码库中（包括某些代码仓库），因此矛盾内容往往位于当前未检出的仓库中。因此，你需要在两个位置进行搜索：

1. 本地检出内容（通过 Grep/Glob）——查找你正在编辑的仓库中的冲突，包括尚未发布的编辑中内容。
2. 所有已发布的 Elastic 文档（通过 Elastic Docs MCP 服务 https://www.elastic.co/docs/_mcp/，无需身份验证）——查找所有已发布文档中的冲突，无需在本地检出对应仓库。

如果当前会话无法使用 Elastic Docs MCP 服务工具（search_docs、get_document_by_url 等），则使用 WebFetch 获取具体的已发布文档 URL。请在报告中注明这两种方法。MCP 只能查看已发布的文档。其他仓库中尚未合并或发布的更改不会显示在其中——请在报告中注明此限制，以便作者了解跨仓库检查仅涵盖已发布内容。

输入

$ARGUMENTS 是包含新增或更新文档的文件或目录。如果为空，请询问用户要检查哪个文件或目录。

步骤 1：阅读新内容

在 $ARGUMENTS 中查找所有 .md 文件。完整阅读每个文件。

阅读时，整理一份声明列表：新内容所作出的事实性断言。记录其原文、文件路径和大致行号。任何类型的内容都可能包含声明——操作步骤、概念页面、参考表格、前提条件说明或建议。请留意以下声明类型：

声明类型	示例
值	默认值、阈值、超时、限制、上限、端口、路径、数量
命名	设置、API 字段、CLI 标志、UI 元素、文件、角色或产品功能的确切名称
步骤和操作流程	步骤顺序、先执行哪项操作、UI 中设置的位置、如何访问某个页面
前提条件和要求	必须先满足的版本、许可证、权限、依赖项或设置要求
概念和定义	术语的含义、概念的描述方式、某项内容属于或不属于什么
可用性和范围	某项内容适用的部署类型和版本范围（serverless、ECE、ECH、自托管、版本范围）
关系	“X 需要 Y”、“X 取代 Y”、“X 已弃用，建议改用 Z”、“X 已移除”、“改用 X 而非 Y”
功能	“X 支持 Y”、“X 不支持 Y”、“Z 中不提供 X”
建议	推荐的默认值、最佳实践指导，以及与其他页面建议不兼容的“我们建议使用 X”

跳过纯主观或说明性且无法产生事实冲突的文字——只收集其他页面可能与之矛盾的断言。

步骤 2：构建搜索词

从声明列表中提取最具体的搜索词：

• 确切的设置名称、API 参数名称、CLI 标志名称
• 功能名称和产品组件名称
• 在多个地方出现的任何具体值（版本号、默认值）
• 足够独特、可在其他地方识别同一主题的短语

替换变量：Elastic 文档使用 {{motlp}}、{{edot}}、{{agent}}、{{ech}} 等变量。当某项声明涉及带有替换变量的产品或功能时，请同时搜索人类可读的名称（例如“Managed OTLP Endpoint”）和替换变量（例如 motlp）。同一项声明可能在已发布的文档中显示为渲染后的文本，在本地源文件中则显示为变量。

优先使用具体的多词搜索词，而不是常见的单个词。后续的本地搜索和跨仓库搜索都会用到这些搜索词。

步骤 3a：搜索本地检出内容

对于每个搜索词，使用 Grep 查找 $ARGUMENTS 以外提及相同主题的 .md 文件：

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

收集匹配的文件路径。排除步骤 1 中已读取的文件。还要排除：

• _snippets/ 目录——片段内容是在包含它们的页面上下文中编写的；片段中的矛盾会通过引用它们的页面体现出来
• release-notes/——内容有意保留历史准确性；不要将特定版本的声明标记为矛盾
• redirects.yml——不是正文内容
• 自动生成的文件（例如 nav.yml、toc.yml）

如果某个搜索词匹配到许多文件，请在继续之前缩小到更具体的子词，或优先选择与 $ARGUMENTS 属于同一产品领域或目录的文件。

步骤 3b：搜索所有已发布的 Elastic 文档（跨仓库）

本地检出内容只是众多仓库之一。若要发现其他仓库发布的文档中的矛盾，请使用 Elastic Docs MCP 服务工具。

对于每项关键声明或搜索词：

1. 使用该词调用 search_docs（如果知道产品或章节，可使用相应筛选条件），查找同一主题的已发布页面。也可以调用 find_related_docs 扩大覆盖范围。这些是主要工具——它们会显示你实际需要对照的候选页面。
2. 对最相关的搜索结果，调用 get_document_by_url 并设置 includeBody: true，以阅读实际内容。矛盾要通过阅读和比较来发现，而不是依据搜索元数据。
3. 也可以围绕主要主题调用 find_docs_inconsistencies（和 check_docs_coherence），以扩大候选范围。将它们的输出仅用于发现：这些工具标记的是在主题上有重叠（主题相同，可能存在冗余）的页面，而不是实际存在分歧的页面。它们返回的每个候选页面仍须在步骤 4 中阅读，并与你的声明列表进行比较——不要仅凭它们的搜索结果就报告矛盾。

如果 MCP 工具不可用：对特定的已发布文档 URL 使用 WebFetch（例如 https://www.elastic.co/docs/reference/opentelemetry/compatibility/limitations）。在报告中注明跨仓库检查使用了 WebFetch 而非 MCP，并说明覆盖范围可能较窄。

跳过与正在编辑的文件相同的页面（即该页面的已发布版本）。与步骤 3a 中已找到的内容去重。

第 4 步：阅读并比较

对于每个候选页面——本地页面（第 3a 步）和已发布页面（第 3b 步）——阅读相关章节。将其中的内容与你的声明列表进行比较：

• 对于同一事项，是否给出了不同的值、限制、路径或名称？
• 是否描述了与新内容冲突的步骤、顺序或流程？
• 是否列出了不同的前置条件、要求、权限或版本？
• 对某个术语或概念的定义是否已不再匹配？
• 是否使用了已更改的设置、参数或功能名称？
• 新内容表示某项功能可用或不可用时，该页面是否说法相反？
• 对于同一事件（引入、弃用、移除），是否给出了不同版本？
• 是否推荐了与新建议不兼容的内容？
• 是否描述了已被新内容取代的行为或指导？
• 其 applies_to 标签是否与新内容中的可用性声明冲突——例如，新内容称某功能处于预览阶段，该页面却将其标记为 GA？

仅标记真正的事实冲突。不要标记措辞、详细程度或文档风格上的差异。

第 5 步：生成报告

撰写发现之前，先评估每项冲突：

可能的修正方向——此技能比较两份文档，不会确认哪一份是事实依据。因此，不要断言哪个页面正确；应指出证据倾向于哪一方，以便撰写者和 SME 做出最终判断：

• Review draft — 多个相互独立的现有来源说法一致，或明确的限制/警告说明直接与新声明矛盾（这是强烈信号，但仍需确认）
• Review existing — 新内容看起来是有意更新的（例如，附近的版本说明或变更日志条目表明此更改是有意的）
• Verify both — 具体值或声明相互冲突，且没有明确迹象表明哪一方反映了当前产品行为；SME 必须先确认，再更新任一页面

严重程度：

• High — 用户按照任一页面操作都会得到不同结果，并且可能导致问题。无论修正方向如何，所有 High 级别发现都会阻止合并，因为冲突本身就是问题。
• Medium — 用户会获得不一致的信息，但不一定导致问题。作为后续事项记录。
• Low — 细节差异（例如缺少限定条件、最低版本要求或不完整列表）。作为后续事项记录。

以结构化报告的形式呈现发现，并分为本地和跨仓库两部分，让撰写者清楚哪些可以直接修复，哪些位于其他仓库。对于每项矛盾：

1. Location — 对于本地文件，使用可点击的 Markdown 链接：[path/to/other-file.md:42](path/to/other-file.md#L42)；对于已发布页面，提供文档 URL
2. Severity — High / Medium / Low
3. Direction — 必须严格使用以下三个值之一：Review draft / Review existing / Verify both。此字段中不要附加文件名、限定语或括号说明——如需补充说明，请放在 Recommendation 字段中。
4. Claim type — 使用以下类型之一：Values、Naming、Steps/Procedure、Prerequisites、Concepts/Definitions、Availability/Scope、Relationships、Capabilities、Recommendations
5. Contradiction — 说明现有内容与新内容分别表达了什么；较短的内容应引用原文
6. Recommendation — 建议可能的修正方向及其所属位置；务必注明采取行动前需要 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）。

最后用一行总结：“发现 N 处矛盾（X 处本地，Y 处跨仓库），其中 B 处为高严重性问题——合并前请解决。”（如果没有问题，则写“未发现矛盾。”）提醒撰写者，跨仓库检查仅涵盖已发布的文档，因此不包括其他仓库中尚未发布的更改。对于正确状态不明确的任何发现，请注明在修改任一页面前需要 SME 确认。