reviewing-document-discovery

reviewing-document-discovery — SKILL.md

バリアント： 標準 · 使用する場面： 作成予定のドキュメントの計画（プロジェクトで作成するドキュメントの一覧）を評価し、その計画に基づいて作成を開始するのに十分妥当か判断したうえで、対応可能な指摘事項とともに VERDICT: approve|revise を出力する場合です。

概要

このスキルは、作成されたドキュメント計画に対する受け入れゲートです。project-document-discovery が作成した計画を、独立した立場からレビューします。計画（およびその計画の対象となったアイデア／アーキタイプ）を手にしたレビュアーがこのスキルを読み込むと、次の問いに答えます。ドキュメントの構成は適切か。つまり、バランスが取れ、網羅的で、実際に作成可能であり、作成を開始するのに十分妥当か。 固定された14項目の基準（当初の9項目＋v2.0.0で追加された3つの出力契約条件＋v3.0.0で追加された2つのマニフェスト完全性条件）を適用し、機械で解析できる単一の判定と、作成者が対応するための指摘事項を出力します。

この基準は、発見スキルのセルフチェック（ステップ9、v6.0.0）と1対1で完全に同じ内容です。発見スキルは、適切な計画を作成するためにこれら14項目をセルフチェックします。このスキルも同じ14項目を独立して検証します（自分の課題を自分で採点することはできません）。このスキルはレビュー専用です。計画を作成、修正、再計画することはなく、指摘事項を報告し、作成者が修正します。

有効にするタイミング

• ドキュメントを作成する前に、作成されたドキュメント計画／マニフェストについて承認または修正の判断が必要な場合。
• project-document-discovery（または同等のもの）が作成した計画に対する独立したゲート役を務める場合。
• 前回の revise に基づいて修正された計画を再評価する場合、または変更案（既存の計画＋明示された変更 → 差分）を評価する場合。

次の場合は有効にしないでください。

• 単一の作成済みドキュメントの内部品質（PRD、アーキテクチャドキュメントなど）を評価する場合 — そのドキュメントの種類に対応するレビュアーを使用してください。
• 完成したドキュメント一式が相互に整合しているかを評価する場合 — reviewing-document-set を使用してください（これは作成済みドキュメント群のゲートであり、このスキルは事前計画のゲートです）。
• 計画を作成する場合 — それは project-document-discovery の役割です。このスキルはレビュー専用です。

入力

• 発見スキルの出力形式で作成されたドキュメント計画 — 各ドキュメントの内容を示す what、作成者の役割、ツール／プロバイダー、スキル、および depends_on を含むリスト。
• 計画の対象となったアイデア＋アーキタイプ — このプロジェクトで何が重要な要素で、何が水増しにあたるかを踏まえて、バランスを評価するために必要です。
• （変更案の場合のみ）以前の計画＋明示された変更 — 差分が変更範囲に限定されているかを評価するために必要です。

アイデア／アーキタイプが不足している場合は、判断の手がかりが足りないということです（判断できる範囲で評価し、判断できない点を指摘してください）。プロジェクトの意図を決して捏造しないでください。

ワークフロー

この方法では、14項目を評価してから判定を出します。まず計画全体（およびアイデア／アーキタイプ）を読みます。

ステップ1 — 全体像を把握する

アーキタイプ（小規模なCLIツール、UIを備えたSaaS、ML製品では、それぞれ必要となるドキュメント構成が大きく異なります）と、計画がグリーンフィールドか変更案（以前の計画＋明示された変更）かを確認します。有能な発見プロセスによって計画が作成されたと想定したうえで、独立した立場から確認し、見過ごされた可能性のある漏れを探します。

ステップ2 — 14項目を評価する

1. アーキタイプに比例していること。 セットの規模はプロジェクトに応じたものです。過剰選択（CLI ツールに PRD ＋ワイヤーフレーム＋デザインシステムを用意するなど）も、不足選択（負荷を支えるドキュメントを、簡素に見せるために削除するなど）もありません。固定の分類体系ではなく、アーキタイプを基準に判断してください。
2. 基盤となるドキュメントが含まれていること。 機能を定義するドキュメント（PRD／機能仕様書。UI 製品の場合はデザインドキュメント）がセットに含まれています。
3. ドキュメントごとの本番要件。 すべてのドキュメントに、作成者＋レビュアーの roles ペア（ID がちょうど 2 つ、順序は [author, reviewer] で、アーキタイプと一致すること。エンジニア／ストラテジストは [document-author, document-reviewer]、デザイナーは [designer, design-reviewer]）＋ツール／プロバイダー＋作成とレビュー両方の skills（例：[authoring-prd, reviewing-prd]）が設定されています。
4. ドキュメントごとの depends_on。 すべてのドキュメントに depends_on があり、セットに含まれるものに限定されています。
5. 依存関係グラフが非循環であること。 組み立て後の（枝刈り済みの）depends_on グラフに循環がなく、要件 → デザイン → デリバリー → ドキュメントの順にエッジが流れています。
6. 孤立したドキュメントがないこと — 最終成果物の例外あり。 すべての中間ドキュメントは、別のドキュメントに情報を渡すか、別のドキュメントから情報を受け取ります。単体で出荷可能な最終成果物であるリーフ成果物（LICENSE／CHANGELOG／SECURITY.md、また多くの場合 README）で、depends_on: [] が設定され、後続のドキュメントで参照されないものは、孤立したドキュメントには該当しません。これを問題として指摘しないでください。上流から何も読み込まず、かつ他のドキュメントからも参照されない中間ドキュメントのみが孤立したドキュメントです。
7. 水増しがないこと。 プロジェクトで使用しないドキュメントは含まれていません。
8. 未知のタイプにも対応できること。 認識されていないタイプは推測ではなく、調査・作成するものとして計画に含まれています。カタログにないという理由だけで、必要なタイプが黙って省略されていません。
9. （修正時のみ）差分が変更範囲に限定されていること。 修正時は、変更または追加されたドキュメントとその DAG エッジのみが変更されています。変更のない計画を再導出しておらず、再度枝刈りしたグラフも引き続き非循環です。（新規計画には該当しません。）
10. capability_map キーが存在し、内容が揃っていること。 出力 JSON にトップレベルの capability_map キーが含まれています。v2 の分類クラスタ 10 個すべてのサブキー（archetype、domain、regulatory、scale、security、integrations、ui、data_ml、infrastructure、business）に加え、モデルが作成する prior_art_triggers ブロックも含まれています。ここでは存在と整合性のみを確認します。トリガーの正しさは決定論的バリデーター（scripts/validate.py`）が検証するため、ここでトリガーの式を再導出しないでください。（v1.x の出力には該当しません。4.0.0 の出力から適用されます。）
11. product_capabilities キーが存在し、レコード形式が正しいこと。 出力 JSON にトップレベルの product_capabilities 配列が含まれています。各レコードには必須フィールド（id、name、scope、owns、has_ui、has_api、has_persistence）があります。リストには L1 レコード（parent フィールドがない、または parent: null のレコード）が 4～10 個含まれています。件数が 4～10 の範囲外の場合は、指摘事項として報告してください（ガイダンス違反であり、ハードゲートではありません）。（v1.x の出力には該当しません。）
12. manifest が "manifest" キーの下にネストされ、機能ごとのエントリーが存在すること。 出力 JSON には manifest キーがあります（ドキュメント一覧がルートレベルに置かれていません）。各ドキュメントエントリーには type と scope フィールドがあります。有効な各機能に対応する機能ごとのエントリー（feature-spec-{id}）が存在します。ファンアウトフラグ（has_ui、has_api、has_persistence）は、生成された機能ごとのドキュメントエントリーと一致しています。（v1.x の出力には該当しません。）
13. 5 つの manifest メタセクションすべてに内容があること。 manifest.capabilities には docs が常に含まれ、ui.has_ui: true の場合は design も含まれています。ビルドレベルの機能（auth、ci、vcs、storage など）は含まれていません。manifest.roles、manifest.skills、manifest.tools はドキュメントセットに基づいて設定され、空配列 [] ではありません。manifest.roles には、存在する各アーキタイプの作成者／レビュアーの完全なペアが含まれています（エンジニア／ストラテジストのドキュメントがある場合は document-author ＋ document-reviewer、デザイナーのドキュメントがある場合は designer ＋ design-reviewer）。また、すべてのロールエントリーはペルソナのみで構成され（skills／tools フィールドがありません）。manifest.skills の各エントリーには version: null、source: null、設定済みの purpose、空でない requirements リストがあります。すべてのスキルエントリーとロールエントリーには resolved_id と match_status があり、どちらも検出時には null です。承認ゲートで解決されるため、version／source／resolved_id／match_status が null であることを不足として指摘しないでください。（v2.x 以前の出力には該当しません。）
14. すべてのドキュメントエントリーに capability スカラーがあること。 manifest.documents 内のすべてのドキュメントエントリーに、文字列スカラー（"docs" または "design"）を含む capability フィールドがあります。配列形式の "capabilities": [...] を使用するエントリーは、この条件を満たしません。（v2.x 以前の出力には該当しません。）

Step 3 — 判断して出力する

調査結果を総合します。承認するのは、計画が適切な規模で、十分で、実行可能かつ非循環である場合です。薄いアーキタイプに見合った簡潔な計画を、適切な規模であるにもかかわらず誤って修正指示してはいけません。実際に明示できる不足（過剰／過少な選定、プロデューサーまたはdepends_onの欠落、循環、中間成果物の孤立、不要な水増し）がある場合は修正を求めます。以下の出力仕様に従って出力してください。

ルール

厳守するルール（絶対に違反しないこと）：

• 最終判定は1つだけ。 全体計画に対する判定を、最後の行に必ず1行だけ出力します — VERDICT: approve または VERDICT: revise。（通常、呼び出し元は最後のVERDICT:行だけを読み取ります。）
• 誤った修正指示をしない。 適切な規模の計画は承認します。薄いアーキタイプに見合った簡潔な計画は承認であり、修正ではありません。実際に不足がある場合に限り修正を求め、指摘は1回の作業で対応可能な内容にします（何が問題か、どの文書が対象か、どう直すか）。
• 要件を捏造しない。 評価するのは結果（適切な規模で、十分かつ非循環の計画）です。アーキタイプに関係のない文書を決して要求しないでください（ステートレスなCLIにデータモデル、ライブラリにワイヤーフレームを要求するなど）。特定の標準への言及を必須にしたり、カタログに載っているというだけで文書を要求したりしてはいけません。計画は意図的にオープンエンドです。
• レビューのみ。 作成、修正、再計画は行わず、指摘を報告してください。修正するのはプロデューサーです。
• 最終成果物の例外は重要です。 リーフ成果物（LICENSE／README／CHANGELOG）を孤立文書として決して指摘しないでください（条件6）。

注意点

• 簡潔な計画に誤って修正を求めること。 薄いCLIツールの計画（README＋短い設計メモ）は、不完全ではなく適切です。適切な規模かどうかは絶対的なチェックリストではなく、アーキタイプに照らして判断します。
• リーフ成果物を孤立文書として指摘すること。 depends_onも下流の参照先もないLICENSE／README／CHANGELOGは、出荷可能な最終成果物であり、孤立文書ではありません（条件6）。これは誤った修正指示の最も一般的な原因です。
• 分類体系すべてを要求すること。 プロジェクトに関係なく、カタログのすべての分類／オーバーレイを要求すると、ディスカバリースキルが避けようとしている重厚な必須分類体系を再現することになります。これは過剰な選定であり、あなたが見つけるべき問題であって、引き起こすべき問題ではありません。
• 文書自体のレビューに逸れること。 PRDの品質を評価するのはPRD担当レビュアーの役割です。ここでは、計画が適切な文書セットを選び、依存関係を正しく結んでいるかだけを評価してください。
• 修正時に計画全体を再検証すること。 修正時は差分（条件9）を評価してください。変更されていない、すでに適切な計画を再度問題にしてはいけません。

アンチパターン

• 判定が最後の行にない、または判定が複数ある。
• アーキタイプに不要な文書を要求する（「すべてのプロジェクトにPRDが必要」など）— 要件の捏造です。
• 薄いアーキタイプに見合った簡潔な計画を、規模が小さいという理由で修正する。
• リーフ成果物を孤立文書として指摘する。
• 指摘を返す代わりに計画を書き直す。

出力

指摘レポートを出力します。実行可能な指摘は0件以上とし、各指摘で対象文書と修正方法を明示します。その後に、最終行としてVERDICT: approve|reviseを必ず1つだけ出力します。reviseの場合、指摘事項が、プロデューサーが計画を修正するための実行可能なリストとなります。抽象的な利用者は、修正を振り分けるオーケストレーターと、計画を修正するディスカバリーパスです。

関連

• project-document-discovery — このスキルがゲートする計画を作成する作成側の対となるものです。そのステップ9のセルフチェック（v6.0.0）が、この14項目の条件の唯一の参照元であり、両者は1対1で対応しています（作成者による自己修正と、この独立したゲート）。
• reviewing-document-set — 作成済みドキュメントの一貫性を確認するゲートです（完成したドキュメント同士が、作成後に整合しているか）。このスキルは、事前の計画を確認するゲートです（ドキュメントの作成前に、計画が妥当か）。両者は組み合わせて使うもので、重複はありません。
• ドキュメント種別ごとのレビュアー（reviewing-prd、…） — 作成済みドキュメント1件の内部品質を評価します。このスキルは、対象一式を決めた計画を評価します。
• design-review — 一般的な設計ドキュメント／仕様書／§15 の実装計画をゲートしますが、ドキュメント計画／マニフェスト（別の成果物）はゲートしません。そのため、両者に適用除外はありません。
• このスキルで運用する実践 — ISO/IEC/IEEE 15289（ライフサイクル情報項目とテーラリング）、適正な規模／「必要十分」、要件→設計→納品の DAG — については、references/sources.md を参照してください。

段階的な情報開示

• references/plan-quality-bar.md — 14項目の条件ごとの合格／不足の判定基準と、具体的な指摘例（特に条件1／6／9／10／11／12／13／14で読み込んでください）。
• references/sources.md — 判定基準の調査根拠。

本文の上限

• description は1,024文字以下（agentskills.io の上限。リスト表示では description と when_to_use の合計が1,536文字で切り詰められます）。
• 本文は約500行／5,000トークン以下 — 大量のコンテンツは references/ に置いてください。

変更履歴

• 1.5.0 (2026-07-10) — project-document-discovery 6.0.0（スキルの意図と解決フィールド）に対応した追加更新です。条件13では、すべての manifest.skills エントリーに入力済みの purpose と空でない requirements リストが含まれ、すべてのスキルエントリーとロールエントリーに resolved_id と match_status が含まれることを新たに求めます（検出時点では両方とも null です。既存の version: null の扱いと同様に、ギャップとはみなしません）。検出側の Self-check 項目13と1対1で単一ソース化しています。ほかの13個の条件に変更はありません。

• 1.4.0 (2026-07-09) — project-document-discovery 5.0.0（マニフェストのレビュー用ロール）に対応した追加更新です。条件3では、作成者とレビュー担当者の roles の組み合わせ（アーキタイプに一致する [author, reviewer] の順序の2つのID）に加え、各ドキュメントの作成スキルとレビュー用スキルの両方を確認するようになりました。条件13では、存在する各アーキタイプについて manifest.roles に完全な組み合わせが含まれ、各ロールエントリーが純粋なペルソナ（skills／tools を含まない）であることを新たに求めます。検出側の Self-check 項目3および13と1対1で単一ソース化しています。ほかの12個の条件に変更はありません。

• 1.3.0 (2026-06-26) — project-document-discovery 4.0.0（capability-map v2）に対応した更新です。条件10を、v2の10個の分類クラスター（team を削除し、business と integrations を追加）と、新たにモデルが作成する prior_art_triggers ブロックに書き換えました。存在と一貫性のみを確認します。トリガーの正しさは決定論的バリデーターの役割です（数式を再計算しません）。生成側のv2分類と1対1で単一ソース化しています。ほかの13個の条件に変更はありません。

• 1.2.0 (2026-06-21) — project-document-discovery v3.0.0に対応した追加更新です。条件を2つ追加しました。条件13では、マニフェストの5つのメタセクションがすべて入力済みであること（capabilities／roles／skills／toolsが空でないこと、ビルドレベルのcapabilityがないこと、skillsのversion／sourceがnullであること）を確認し、条件14ではすべてのドキュメントエントリーにスカラー形式のcapabilityが含まれること（配列形式ではないこと）を確認します。説明を「14条件の基準」に更新しました。元の12個の条件に変更はありません。

• 1.1.0 (2026-06-21) — project-document-discovery v2.0.0の出力契約に対応した追加更新です。新たに3つの条件（10、11、12）を追加しました。capability_mapキーが存在し、10個すべてのクラスターが含まれること、product_capabilitiesキーが存在し、必須フィールドを備えたL1レコードが4～10個あること、マニフェストが「manifest」キーの下にあり、各エントリーにtype／scopeが含まれ、フラグに一致するcapabilityごとの展開エントリーがあることを確認します。元の9個の条件に変更はありません。説明を「12条件の基準」に更新しました。

• 1.0.0 (2026-06-15) — 初回のレビュー済みリリースです。生成されたドキュメントプランに対する独立したゲートであり、9つの条件を project-document-discovery の Self-checkと1対1で単一ソース化しています。