ensure-docs

ドキュメントカバレッジの確認

コードベース全体のドキュメントカバレッジを確認し、不足箇所を報告して、不足しているドキュメントを生成します。エージェントがサブエージェントに対応している場合は、検出された言語ごとに検証担当を 1 つずつ並行して実行します。対応していない場合は、言語ごとに同じ検証を順次実行します。どちらの場合も出力は同じです。

カバレッジには相互に補完する 2 つの観点があり、健全なプロジェクトには両方が必要です。

1. シンボルカバレッジ — 関数、クラス、モジュールが、その言語の標準（docstring、JSDoc、GoDoc）に従ってドキュメント化されているか。以下の言語ごとの検証で確認します。
2. Diataxis の種類のバランス — ドキュメント一式全体が、学習用のチュートリアル、タスク用のハウツーガイド、参照用のリファレンス、理解用の解説という、ユーザーの 4 つのニーズすべてに対応しているか。コードベースの docstring カバレッジが 100% でも、新規ユーザーが使い始めるための方法がない場合があります。以下のDiataxis バランスチェックを参照してください。

ワークフロー

手順を順番に完了してください。各手順の合格条件を満たすまで、次に進まないでください。

1. 言語の検出 — references/workflow.md のフェーズ 1（言語の検出）に従います。

   • 合格条件： 検証する各言語について、一致するソースファイルが少なくとも 1 つあることを示す根拠（件数またはコマンド出力）があります。該当する言語がない場合は、「該当する言語はありません」という簡潔なメッセージを出して終了し、検証担当を実行しないでください。

2. 標準の読み込み — 同じリファレンスファイルで、検出した言語に該当するセクション（言語標準、検証プロンプト、統合形式）を読みます。

   • 合格条件： 検証を開始する前に、言語ごとに適用する標準（例：Google docstring、JSDoc、GoDoc）を明示できます。

3. 検証 — リファレンスの検証プロンプトと JSON 出力形式（フェーズ 2）を使用して、該当する言語をそれぞれ検証します。エージェントがサブエージェントに対応している場合は、言語ごとに検証担当を 1 つずつ並行して実行します。対応していない場合は、順次実行します。

   • 合格条件： 完了した検証ごとに、language、files_scanned、および findings（空の場合もある配列）を含む、解析可能な JSON が返されます。

4. Diataxis バランスチェック — プロジェクトに既存のドキュメント（例：docs/ ツリー、README、wiki）を対象に、Diataxis の種類のバランスチェックを実行します。

   • 合格条件： 4 種類（チュートリアル、ハウツー、リファレンス、解説）それぞれについて、該当するニーズに応えるドキュメントがプロジェクトに少なくとも 1 つあるかを明示でき、不足している種類や内容が薄い種類を記録しています。

5. 統合レポート — フェーズ 3 に従って結果を統合します（概要表、重大度別の分類、必要に応じた詳細な指摘事項）。シンボルカバレッジと併せて、Diataxis のバランスも含めます。

   • 合格条件： 監査完了を宣言したり修正を提案したりする前に、シンボルカバレッジと Diataxis の種類のバランスの両方を網羅した統合レポートを、ユーザーが確認できます（その場で表示するか、合意したパスに書き込みます）。

6. 生成 — --report-only が設定されていない場合に限り、フェーズ 4 に従って選択肢を提示します。ドキュメントの編集は、生成するというユーザーの明示的な選択を得てから行います。Diataxis の種類に不足がある場合は、インラインで生成するのではなく、該当する種類のドキュメント生成を draft-docs に依頼します。

   • 合格条件： ユーザーが生成を含む選択肢を選ぶまで、不足箇所に対するドキュメントの編集は行いません。ユーザーが辞退するか、レポートのみを選択した場合は、レポートの提示後に終了します。

7. 編集後の検証 — 生成を行った後、ツールがリポジトリに存在する場合は、変更した言語についてリファレンスのフェーズ 5 にあるリンターコマンドを実行するか、実行を提案します。

   • 合格条件： リンターの実行が完了し、出力が記録されているか、「N/A」として一行で理由（例：ツールが設定されていない）を示しています。残っている問題は一覧表示されるか、解消されています。

Diataxis タイプのバランスチェック

プロジェクトの文章によるドキュメント（docs/ ツリー、README、Wiki、ドキュメントサイト）を調査し、存在するものを Diataxis の4つのタイプに分類します。docs-style/references/diataxis-compass.md に従い、コンパスを使って「行動か認識か？習得か適用か？」を基準に分類します。

バランスを次の表で報告します。

タイプ	存在する？	備考
チュートリアル（学習）	あり／なし／不十分	例：「スタートガイド／最初のプロジェクトのガイドがない」
ハウツー（タスク）	あり／なし／不十分	例：「docs/how-to/ に複数のタスクガイドがある」
リファレンス（参照）	あり／なし／不十分	例：「API リファレンスは自動生成されるが、CLI リファレンスがない」
解説（理解）	あり／なし／不十分	例：「アーキテクチャ／設計根拠のドキュメントがない」

次の項目を優先順位順に指摘します。

1. 欠けているタイプ — そのユーザーニーズに応えるドキュメントがありません。最もよくある、かつ最も深刻な不足はチュートリアルの欠如です。リファレンスが網羅的でも、新規ユーザーに始める方法を示せないことがあります。
2. 不十分なタイプ — 存在はするものの、プロジェクトの主要な機能や対象領域をカバーしていません。
3. 複数のタイプが混在するドキュメント — 1つのページが2つのタイプを兼ねようとしています（例：ハウツーにリファレンスの表を埋め込んでいる）。improve-doc に従って分割することを提案します。

不足しているタイプについて、内容のないひな形を生成する提案はしないでください。Diataxis の「改善を通じて作業する」という原則に従い、次に追加または修正すべき最も価値の高いドキュメントを1つ提案し、draft-docs を使ってそのドラフトを作成することを提案します。

注意事項

• --report-only を使うと、生成をスキップできます。
• テスト用ヘルパーを除き、テストファイルは避けてください。
• レポートの出力は、参照ファイルにある言語固有の規約に沿わせてください。
• Diataxis のバランスチェックはドキュメント一式全体を対象とします。言語ごとのシンボルカバレッジとタイプのバランスは別々の指標です。両方を報告してください。