Back to Details

verify-openspec-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Verify OpenSpec docs

验证OpenSpec文档

Check finished docs prose against reality. The point of a fresh context is that the reviewer hasn't watched the prose get written, so it can't be talked into the author's assumptions.
This skill runs only when the user asks for it. Drafting is owned by 
write-openspec-docs
; don't invoke this from inside a drafting session unless the user requests a verification pass.
对照实际情况检查已完成的文档内容。使用全新上下文的意义在于，核查者并未全程参与文档撰写，因此不会受作者固有假设的影响。
本skill仅在用户主动要求时运行。文档起草由
write-openspec-docs
负责；除非用户要求进行验证，否则请勿在起草会话中调用本skill。

Scope the run

确定运行范围

  1. Confirm the target: a page, one 
    ##
    section, or a list of changed claims. If invoked without a target, ask.
  2. Read the README at the root of the docs tree the target lives in; its invariants and page map are part of what gets checked.
  3. One subagent per unit (one 
    ##
    section, or the stated claim list). A full page is several subagents, run in parallel.
  1. 确认核查目标：某一页面、某一个
    ##
    章节，或一组修改后的声明。若调用时未指定目标，请询问用户。
  2. 阅读目标所在文档树根目录下的README；其中的不变规则和页面映射也是核查内容的一部分。
  3. 每个核查单元对应一个子代理（一个
    ##
    章节或指定的声明列表）。完整页面需多个子代理并行运行。

Spawn the reviewer

生成核查代理

General-purpose subagent. Subagents don't inherit skills, so the prompt hands the reviewer everything by path. Fill every placeholder, make every path absolute, and send:
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.
通用型子代理。子代理不会继承skill，因此需通过路径将所有必要信息传入提示词。填充所有占位符，使用绝对路径，并发送以下内容：
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.

Handle the report

处理核查报告

  • Default is report, not rewrite: show the user the findings ranked most severe first, each with the quoted line and one-line fix, plus what was verified and how, and any claim the reviewer couldn't verify.
  • Apply fixes only when the user asked for a verify-and-fix run or approves the findings. A verifier can also be wrong: rejections go in the report with your reason, so the user can overrule you.
  • If an applied fix changed a factual claim, verify again, scoped to the changed claims. Typo and wording fixes don't need a second pass.
  • Two passes without converging means stop and take it to the user. Don't polish in a loop.
  • 默认仅生成报告，不重写文档：向用户展示按严重程度排序的核查结果，每个结果需包含引用内容、问题说明和一行修复建议，同时列出已验证的内容及验证方式，以及核查者无法验证的声明及原因。
  • 仅当用户要求“验证并修复”或批准核查结果时，才应用修复。核查结果也可能有误：若拒绝修复，需在报告中说明原因，以便用户推翻决策。
  • 若应用的修复修改了事实性声明，需针对修改后的声明再次进行验证。拼写错误和措辞修改无需二次验证。
  • 若两次验证仍未达成一致，需停止操作并提交给用户处理。请勿陷入循环打磨。