verify-docs-findable

verify-docs-findable — 新しい視点でドキュメントを読み解く

この手順で検証する洞察：網羅されていることと、見つけやすいことは別です。 すべてのドキュメントを列挙したインデックスがあっても（さらに「すべてのドキュメントがインデックスに載っている」チェックに合格していても）、基本的な質問に答えるために読者が5回もリンクをたどり、結局ソースコードに頼ることがあります。正直な検証方法は、そのリポジトリを見たことがない人に質問を渡し、ドキュメントだけを使ってどこまでたどり着けるかを見ることです。新鮮な状態の低コストなエージェントが、その役を担います。

なぜ HAIKU なのか、そしてなぜ「ドキュメントのみ」なのか

• Haiku（小型で低コストのモデル）を、セッションのコンテキストなしの新鮮な状態で使います。 目的は、優秀な読者ではなく、予備知識のない読者による検証です。あなたのコンテキストを知る高性能モデルなら、ソースを grep し、情報の不足を推論で補って、ドキュメントの問題を 覆い隠して しまいます。ドキュメントのみを使うよう指示した Haiku なら、その問題が表面化します。
• 「ドキュメントのみを使い、インデックスから始める。」 検証者が回答のためにソースコードを開く必要が生じた時点で、ドキュメントは役目を果たせていません。それが問題を示すサインです。指標となるのは、インデックスから回答までに必要なステップ数です。

手順

1. 質問を用意する（3～8件）

繰り返し尋ねられ、重要で、誤解されている質問を検証します。実際に時間を取られる質問が対象です。情報源は次の順に確認します。

• 今回のセッションでユーザー（またはあなた）が混乱したこと。最も有力な情報源です。
• ドキュメントが提供すると うたっている「正式な回答」。通常、ドキュメント一式には伝えるべき事実が約5～8件あります。それらを検証します。
• どちらもない場合は、ユーザーに質問を尋ねるか、コーパスの最上位のトピックから推測します。些細な質問をでっち上げず、実際のコントリビューターに必要なことを検証します。

各質問は、ドキュメントのタイトルではなく、読者が実際に尋ねる質問として表現してください。

2. 質問ごとに、新鮮な状態の Haiku 検証者を1つ起動する（並列実行）

Agent ツールで model: "haiku"、run_in_background: true を指定し、質問ごとに1つ起動します。全員に同じ厳密なテンプレートを渡します（<QUESTION> を置き換えてください）。

あなたは、<repo path> を初めて開く新しいエンジニアです。リポジトリのドキュメントのみを使って回答してください。インデックス（<the index file(s)>）から始め、リンクをたどってください。ソースコードを読むより、ドキュメントを優先してください。 質問：<QUESTION> 報告事項：（a）回答、（b）見つけた正確なファイル名、（c）インデックスから何ステップかかったか（リンクから直接たどれたか、それとも探し回ったか）、（d）明確で曖昧さがなかったか、それとも情報が散在していて分かりにくかったか、（e）ドキュメントに記載がなく、ソースコードを読む必要があったか。正直に答えてください。これは、ドキュメントから情報を見つけられるかを検証するものです。

すべて同じメッセージで実行し、並列に進めます。（Haiku＋並列実行で、監査のコストを抑えられます。）

3. 各回答を評価する

シグナル	良好	ギャップ
正確か？	正解と一致する	誤り／不完全 → ドキュメントに誤りがあるか、記載がない
インデックスからのステップ数	1～2	3以上 → 適切なリンクが案内されていない
行き止まり	なし	最初に、誤っているがもっともらしいドキュメントにたどり着いた → タイトルや対象範囲が誤解を招いている
ソースコードが必要だったか？	いいえ	はい → ドキュメントに実際の記載がない
矛盾	—	引用された2つのドキュメントの内容が異なる → 一貫性の問題（すぐに修正）

検証者は矛盾も 追加コストなしで 見つけてくれます。異なる内容を記載した2つのドキュメントを、予備知識のない読者が引用するのは、矛盾を見つける最も低コストな方法です。

4. 問題を修正する

• 3 ステップ以上／行き止まり → インデックスの入口に質問→ドキュメントへの案内を追加します（「回答の決定版：質問 → 唯一のドキュメント」ブロック）。回答を明示することで、5 回の移動が 1 回になります。
• ソースコードが必要 → その事実は文章にはありません。唯一の決定版ドキュメントに記載します。
• 回答が間違っている → ドキュメントが古い、または誤っています。修正します（決定を記録している場合は、削除せず追記します）。
• 矛盾している → ドキュメント間の矛盾を解消します。過去の決定は残し、置き換え済みであることを明記します。
• N 件のドキュメントに分散している → 質問ごとに 1 件のドキュメントへ集約し、ほかのドキュメントからはそのドキュメントを参照するようにします。

5. 再検証する（推測せず測定する）

修正したドキュメントに対して、最も難しい質問を再実行します。ステップ数が変化したこと（例：5 ステップ → 2 ステップ）を確認します。再測定していない修正は推測にすぎません。

出力

簡潔な検索性スコアカード（質問 | 正解 | ステップ数 | 必要なソース | 判定）と、優先順位を付けた修正リストを作成します。修正して再検証した質問については、修正前後の結果を報告します。

注記

• これは「すべてのドキュメントがインデックスに登録されているか」という網羅性チェックとは別のものです。その一段上のレイヤー、つまり見知らぬ人が回答に_たどり着けるか_を測定します。ドキュメントを再構成した後に実施してください。
• 質問セットはリポジトリ内に保持します（例：docs-findability-questions.md）。これにより監査を再現可能にし、コーパスの拡大に合わせて回答の決定版を適切に保てます。
• 規模は小さく（質問 1 件、エージェント 1 つで修正を 1 件スポットチェック）も、大きく（決定版の質問セット全体）もできます。