spec-coverage-assessment

仕様カバレッジ評価

名前付きサーフェスのガバナンス範囲を限定的に調査し、執筆に先立って把握します。 エージェントが手探りの判断で答えがちな3つの問いに答えます。すでに何がカバーされているか、何が未整備か、新しい仕様の境界をどこに設定すべきか、です。 出力はレビュー可能なカバレッジマップの成果物です。仕様、ADR、またはドクトリン追跡対象のエンティティそのものではありません。

名前の衝突 — 書き留める前にお読みください

doctrine coverage（coverage record | verify | forget）は、 要件検証のエビデンス、つまり REQ-NNN が満たされていることが確認されたかどうかを示します。 このスキルとは無関係です。このスキルの出力を、文章、コミット、ドクトリンのエンティティ内で単に「coverage」と呼ばないでください。必ず「仕様カバレッジ」「ガバナンスカバレッジ」、または「カバレッジマップ」と明記してください。このスキルの意味を期待して doctrine coverage の動詞を呼び出してはいけません。また、レビュー担当者に両者を混同させないでください。同じ単語が使われているだけで、両者は異なる軸（要件の証明と、サーフェスに対する仕様の範囲）です。

対象範囲

既存のガバナンスが不明確なサブシステム、クレート、機能、またはコード領域を対象とする場合に、このスキルを使用してください。どの仕様が対象に関係するのか、仕様が現状に合っているか、新しい仕様をどのように切り分けるべきかが、まだ分かっていない状況です。

次の場合は使用しないでください。

• 対象の仕様とその境界がすでに明確で曖昧さがない場合は、/spec-product または /spec-tech に直接進んでください。
• すでに範囲が定まっている仕様を執筆または改訂する場合は、/spec-product / /spec-tech を直接使用してください。このスキルの出力はその入力であり、代替ではありません。
• 要件が満たされていることを証明する場合は、別種の検証エビデンスである doctrine coverage を使用してください。
• コーパス全体の監査や、行ごとの網羅的なレビューを行う場合は使用しないでください。これは限定的な調査です（「終了条件」を参照）。/inquisition や /audit ではありません。

終了条件

/preflight の規律に従い、開始する前に、次の事項を声に出して決めてください。

• 調査の深さ：サーフェスに関係する主張を確認する仕様／ADR／ポリシー（タグ、タイトル、またはキーワードの一致による）を決めます。サーフェスが本当にコーパス全体に関わる場合を除き、コーパス全体を対象にしません。
• インベントリの深さ：モジュール／クレート単位の行数とファイル一覧を確認し、すべてのファイルを読むことはしません。疑わしいモジュールはサンプルとして確認し、最初から最後まで読み通さないでください。
• 上位のギャップと境界の推奨事項が明確で、レビュー可能になった時点で終了します。すべてのアンカー、帰属先のないモジュール、接線的なADRを余すところなく追跡してはいけません。それは監査であり、この作業ではありません。
• サーフェスが小さく、すでに十分な根拠に基づいていると分かった場合は、その旨を早めに伝えて終了してください。この手法の形式を満たすために、ギャップを作り出してはいけません。

手法

1. ガバナンスの全体調査

すでに対象領域に関与すると主張しているものを列挙します。

• doctrine spec list（対象領域に対するタグ／タイトル／キーワードの部分一致で絞り込み）に加え、doctrine search "<surface keyword>"（BM25）を実行して、明確なタグはないものの対象領域に言及している仕様を見つけます。
• アンカーの洗い出し：候補となる仕様ファイルに対し、TOML の生データを [[source]] ブロックで grep します（rg -A2 '\[\[source\]\]' <spec-dir>/**/spec-*.toml）。仕様を 1 つずつ spec show で表示して確認するよりも高速で、漏れも少なくなります。候補を絞り込んだら、doctrine spec show <ID> で表示内容を抜き取り確認します。
• タグ／タイトルの対応付け：候補となる各仕様の tags と responsibilities[]（TOML）を、対象領域の実際のモジュール名と照合します。仕様の説明文が、アンカーによる裏付けなしに「X クレートを所有する」と対象領域について主張している場合もあります。その主張もカバレッジの兆候にはなりますが、現行アンカーよりは弱いものです。
• ADR／ポリシー／標準の調査：doctrine adr list、doctrine policy list、doctrine standard list（部分一致／タグで絞り込み）を実行し、仕様以外で対象領域に関係するガバナンスを調べます。コンポーネントによっては、ポリシーや ADR だけがガバナンスとなっている場合もあります。
• 任意で doctrine relation census／doctrine concept-map を使い、候補となる仕様同士の既存の関連を確認します。ステップ 5 の降下先／親の判断に役立ちます。

2. 対象領域のインベントリ

ガバナンスによる主張とは切り離して、対象領域の実際の範囲を列挙します。

• 指定された領域の下にあるモジュール／クレート／スクリプト／Web ディレクトリを列挙します（rg --files <path>、標準のディレクトリ一覧表示）。
• 行数（tokei、wc -l など）でそれぞれの規模を測ります。これはステップ 4 の規模要因として使います。厳密さは重要ではなく、桁の把握が重要です。
• 後で境界を設定する際に重要な構造上の切れ目を記録します。フロントエンドとバックエンドを分離できるか、クレート境界があるか、明確に異なるスクリプト群があるか、といった点です。

3. カバレッジのマッピング — アンカーの有効性に関する注意点を踏まえて

インベントリ（2）と全体調査（1）を、モジュール／クレート／領域ごとに突き合わせます。

• カバー済み — 現行の仕様への有効なアンカーがある。
• 一部カバー — タグ／タイトル／説明文に記載はあるが、アンカーはない、またはアンカーはあるが古くなっている（注意点を参照）。
• 未カバー — いかなる形のガバナンスも関与していない。

アンカーだけを信頼できる基盤として扱うことはできません。カバレッジとして数える前に、有効性を確認してください。 アンカーは説明的なものであり、強制されるものではありません。現時点では、アンカーされたパスがまだ存在するかを確認する仕組みはありません。実際に、コードが別の場所へ移動した後も、仕様のアンカーがファイルパスを示したままになっていた例が見つかっています。仕様は「カバー済み」に見えても、実際には古くなっていました。「カバー済み」と判断する根拠にするアンカーはすべて、信頼する前にパスが存在することを確認してください（test -e など）。また、次の点にも注意してください。アンカー密度はサブシステムの規模と逆相関することがあります（大規模なサブシステムほどアンカーが少ない場合もあり、規模が大きければカバー済みだと決めつけないでください）。さらに、数値の仕様ディレクトリの隣にあるスラッグのシンボリックリンクは、単純な再帰 grep では二重に数えられます。

4. ギャップの順位付け

未カバー領域と一部カバー領域を、発見順ではなく規模 × 中心性で評価します。

• 規模：ステップ 2 で数えた行数／ファイル数。
• 中心性：その領域がどれだけ重要な基盤となっているか。他のコンポーネントがどれだけ依存しているか、製品ラインの中核となる度合い、他の仕様が依存先としてすでに記述している経路上にあるか、などです。

上位のギャップをいくつか挙げるにとどめ、未カバー領域をすべて網羅した順位表は作成しません。ここで停止条件を適用します。

5. 仕様の境界を提案する

優先度が最も高いギャップごとに、単に指摘するのではなく、どのような形にするかを検討します。

• プロダクトの階層（ドメイン | ケイパビリティ | フィーチャー — feature が最低階層であり、別のフィーチャーの親になる場合もあります）— 新しいプロダクトの意図（PRD）が必要でしょうか。それとも、既存の PRD ですでに なぜ が説明されており、技術仕様だけが不足しているのでしょうか。プロダクト階層が C4 より短いのは意図的です。両者を一致させるために、4 つ目の階層を追加しないでください。
• C4 のレベル（コンテキスト | コンテナー | コンポーネント | コード）— 新しい技術仕様を作成する場合、どのレベルにしますか。通常はコンポーネントまたはコンテナーで止めます。コードレベルは例外です（/spec-tech の独自ガイダンス）。デフォルトにせず、採用する場合は根拠を示してください。
• PRD と SPEC の切り分け — 修正方法は、「すでにこの内容を対象としている既存の仕様にアンカーを追加する」（新しいエンティティは不要）、既存の PRD の下に新しい技術仕様を作成する、または新しい PRD と新しい技術仕様の両方を作成する（プロダクトの意図がまったく存在しない場合）のどれでしょうか。
• 仕様の数 — ギャップはひとまとまりのコンポーネントとして扱えるでしょうか。それとも、ステップ 2 で気づいた構造上の境界で分かれるでしょうか（例：バックエンドエンジンと、別々にリリースされるウェブフロントエンドは、通常 1 つではなく 2 つのコンテナーです）。
• 階層と親の配置 — 提案する仕様は、parent／descends_from の階層のどこに置きますか。既存のコンポーネントと同じ階層、既存のコンテナーの子、またはシステムのコンテキスト仕様の下に置く新しいコンテナーでしょうか。
• 草案の資料 — /spec-product／/spec-tech の工程で草案を作成する際、白紙から始めずに済むよう、既存の RFC、設計ドキュメント、スライスの履歴のうち、どれを資料として使いますか。

6. カバレッジマップの成果物を出力する

調査結果を、レビュー可能な単一の Markdown 成果物としてまとめて終了します（下記の形式を参照）。

# Coverage census — <surface name>

## Governance census
Specs / ADRs / policies / standards found touching the surface, with anchor
status per claim (live / stale / prose-only-no-anchor).

## Surface inventory
Modules/crates/areas with approximate size (loc/file count).

## Coverage map
Covered / partial / dark per area, with the anchor-liveness check applied —
not assumed.

## Ranked gaps
Top gaps by size × centrality, each with a one-line rationale for its rank.

## Boundary proposal
Per ranked gap: product altitude, C4 level, PRD-vs-SPEC split, one-or-several,
descent/parent placement, drafting sources.

## Out of scope / not assessed
What the bounded census deliberately did not chase down, so a reviewer knows
the edges of what was checked.

プロジェクトのランタイム状態の慣例に従った場所（例：.doctrine/state/）に保存します。これは執筆に使う暫定的な入力であり、永続的な種別が用意されない限り、それ自体が作成済みエンティティになるものではありません。

ガードレール

• アンカーを信頼する前に、そのパスが存在することを確認してください。ステップ 3 を参照してください。
• 完全な監査として扱わないでください。網羅的で終わらない調査より、範囲を限定して事前に明示する調査のほうが適切です。確認しなかったことも記載してください。
• 調査結果で裏付けられない仕様の境界を作らないでください。境界が曖昧な場合は、ここで推測せず、/spec-product／/spec-tech に対する未解決の質問として扱います。
• 名前の重複に関する注意を参照し、出力を単に「カバレッジ」と呼ばないでください。
• このスキルの出力が、レビューや明示的な引き継ぎなしに仕様そのものにならないようにしてください。

引き継ぎ

カバレッジマップの成果物は、次の作業への入力になります。

• /spec-product — 提案された PRD レベルのギャップ（プロダクトの意図が不足している場合）に使用します。
• /spec-tech — 提案された技術仕様レベルのギャップ、またはアンカーの修復に使用します。
• バックログ — 誰かが対応する前に、提案された境界を記録しておく価値がある場合に使用します（backlog new）。

このスキルの役割は、レビュー済みのカバレッジマップを作成するところまでです。仕様の文章や要件エンティティ自体は作成しません。