verify-openspec-docs

验证 OpenSpec 文档

对照实际情况检查已完成的文档表述。采用全新上下文的目的是让审阅者没有参与过文案撰写，因此不会被作者的假设说服。

此技能仅在用户提出请求时运行。文档起草由 write-openspec-docs 负责；除非用户要求进行验证，否则不要在起草过程中调用此技能。

确定运行范围

1. 确认目标：一个页面、一个 ## 章节，或一份已更改声明的列表。如果调用时未指定目标，请询问。
2. 阅读目标所在文档树根目录中的 README；其中的不变要求和页面索引也属于检查范围。
3. 每个单元（一个 ## 章节，或指定的声明列表）分配一个子 Agent。完整页面需要分配多个子 Agent，并行运行。

启动审阅者

通用子 Agent。子 Agent 不会继承技能，因此提示词需要按路径向审阅者提供所有内容。填写每个占位符，将每个路径设为绝对路径，然后发送：

You are reviewing one unit of OpenSpec's user documentation before it reaches the docs owner. Be the two hardest readers it will meet: a skeptical developer reading it cold, and a fact-checker with the repo open.

Repo root: <ABSOLUTE REPO ROOT>. Use absolute paths with every tool.

Read first:
1. <DOCS TREE ROOT>/README.md: the page map and standing invariants.
2. <ABSOLUTE REPO ROOT>/.agents/skills/write-openspec-docs/writing.md: the house writing rules.
3. <PAGE PATH>: review only <the section "<HEADING>" | these changed claims: <LIST>>; read the rest of the page for context.

Then check, in this order:

1. Facts. Every command, flag, path, config key, output block, default, and behavior claim. Re-run the terminal commands shown: read-only commands anywhere, anything that mutates state in a scratch directory or not at all. Commands for the AI chat surface (like /opsx:propose) can't run in a shell; verify their names and behavior against the skill sources this repo ships. Check names against src/ and the CLI's own --help. An output block must match what the command actually prints.
2. Examples. Any example spec or change must pass `openspec validate`. Run it when the example exists on disk.
3. Structure. Flag anything that re-explains a topic whose canonical home is another page, or breaks a rule the docs tree's README states.
4. Job fit. Does the unit serve the page's stated job (the one-line statement under the title, if present)? Does the arriving reader get what they came for quickly?
5. Trust and slop. Flag: hype or comfort adjectives (easy, simple, powerful, seamless), claims with no shown evidence, vague generalization where a specific fact belongs, binary contrasts ("not X, it's Y"), colon reveals, importance puffery, summary endings, em dashes, bullet lists that should be prose, and three parallel punchy sentences in a row.

Report findings only, most severe first. For each: quote the line, say what is wrong, and give the fix in one line. For every fact you verified, say how (the command you ran, or the file and line you checked). List any claim you could not verify and why. Do not rewrite the unit. If the unit is clean, say so and list exactly what you verified.

处理报告

• 默认只报告，不重写：按严重程度从高到低向用户展示调查结果，每项包含引用的原文和一行修复建议；此外说明已验证的内容及验证方式，以及审阅者无法验证的声明。
• 只有在用户要求验证并修复，或批准调查结果时才应用修复。验证者也可能出错：如不采纳某项结果，应在报告中说明理由，让用户决定是否推翻这一判断。
• 如果应用的修复改变了事实性声明，应针对已更改的声明再次验证。拼写错误和措辞修正无需二次验证。
• 两轮验证仍无法达成一致时，停止并交由用户处理。不要陷入反复润色。