verify-openspec-docs

OpenSpec ドキュメントの検証

完成したドキュメントの文章が実態に即しているか確認します。新しいコンテキストでレビューするのは、レビュー担当者が文章の執筆過程を見ていないため、作者の思い込みに流されないようにするためです。

このスキルは、ユーザーから依頼された場合にのみ実行します。執筆は write-openspec-docs が担当します。ユーザーが検証を依頼しない限り、執筆セッション中にこのスキルを呼び出さないでください。

実行範囲を決める

1. 対象を確認します。ページ、1つの ## セクション、または変更された主張のリストです。対象が指定されずに呼び出された場合は、質問してください。
2. 対象があるドキュメントツリーのルートにある README を読みます。不変条件とページマップも検証対象です。
3. 単位ごとにサブエージェントを1つ起動します（1つの ## セクション、または指定された主張のリスト）。ページ全体の場合は複数のサブエージェントを並行して実行します。

レビュアーを起動する

汎用のサブエージェントを使用します。サブエージェントはスキルを引き継がないため、プロンプトにはすべての情報をパスで渡します。すべてのプレースホルダーを埋め、すべてのパスを絶対パスにして、次を送信します。

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.

レポートに対応する

• デフォルトでは修正せず、報告します。最も重大なものから順に、該当する行の引用と1行の修正案を添えてユーザーに指摘事項を示し、検証した内容と方法、さらに検証できなかった主張があればそれも伝えます。
• 修正を適用するのは、ユーザーが検証と修正を依頼した場合、または指摘事項を承認した場合に限ります。検証者が誤っている可能性もあります。異議がある場合は、その理由とともにレポートに記載し、ユーザーが覆せるようにします。
• 修正を適用して事実に関する主張が変わった場合は、変更した主張を対象に再検証します。誤字や表現の修正では、再検証は不要です。
• 2回検証しても収束しない場合は、そこで止めてユーザーに確認します。延々と磨き続けないでください。