epistemic-mapper

認識マップ

プロジェクトのドキュメントとコードから、そのプロジェクトの知識の状態を抽出し、すべての観察事項を4つの象限に分類して、結果を標準の EPISTEMIC-MAP.md に記録します。これは引き継ぎ用の成果物です。プロトタイプの構築者が、文書化されていない暗黙知を大量に抱えているために作成されます。契約が締結され、チームが引き継ぐ段階で、その知識を今すぐ記録するか、本番環境で苦労して再発見するかのどちらかになります。

                    HIGH CERTAINTY (validated)
                              |
          [ ASSUMPTIONS ]    |    [ FACTS ]
          Unknown Known      |    Known Known
          nobody wrote it    |    proven, cited
          down, but the      |    evidence
          code/docs rely     |
          on it              |
    ------------------------ + ------------------------
                              |
          [ RISKS ]           |    [ QUESTIONS ]
          Unknown Unknown     |    Known Unknown
          blind spots, found  |    explicit open
          only by looking     |    gaps, already
          across everything   |    flagged somewhere
                              |
                    LOW CERTAINTY (unvalidated)

他の更新され続けるドキュメントとの関係

CONSTRAINTS.md には外部から課された厳格な制約が記載されています。JARGON.md には用語の定義が記載されています。ARCHITECTURE.md には構造上の決定が記載されています。AGENTS.md にはエージェントの動作とオーケストレーションが記載されています。EPISTEMIC-MAP.md は、この4つとは性質が異なります。何が真実かを記録する台帳ではなく、何が真実かをどの程度確信しているかを示すマップです。抽出を始める前に、ほかの更新され続けるドキュメントがあれば目を通してください。理由は2つあります。

1. 重複を避けます。 既知の事実がすでに CONSTRAINTS.md に記載されているか、JARGON.md で定義されている場合は、新たな事実として書き直すのではなく、ファイルとセクションを参照してください。EPISTEMIC-MAP.md は、ほかの更新され続けるドキュメントを参照するものであり、それらと競合するものではありません。
2. 確信度の初期値を設定します。 CONSTRAINTS.md の項目に裏付けられた主張は、得られる限り十分に検証されています。既定では、再検討が必要なものではなく、確信度を CONFIRMED とした既知の事実として扱ってください。

蓄積していくほかの更新され続けるドキュメントとは異なり、このドキュメントは縮小していくことを想定しています。 検証された仮定はすべて事実になります。回答が得られた質問はすべて解決済みになります。調査されたリスクは、修正されて解消するか、正式に受け入れられて既知の未知事項に移され、隠されたままではなく追跡されるようになります。再実行後も未解決の項目数が横ばいか増加している場合、引き継ぎが実際には進んでいない兆候です。大きなファイルを網羅性の証とみなすのではなく、エグゼクティブサマリーでその点を率直に伝えてください。

認識マップを作成する際に絶対にしてはいけないこと

• カテゴリースラッグを新たに作成してはいけません。 影響が及ぶ先に基づいて、正規の5つのスラッグから最も近いものを選び、具体的なパターンはステートメント／推論のテキストに記載してください。それ以外はmerge_epistemic_map.pyが拒否し、エラー自体にフォールバックルールを説明します。実例はreferences/schema.mdを参照してください。
• サブエージェントのプロンプトを書く際、記憶を頼りに調査結果のスキーマを言い換えたり、再構成したりしてはいけません。 references/schema.mdのフィールド名と象限の値を一字一句そのまま引用してください。フィールド名を変更（statementをobservationにするなど）したり、象限名を短縮（known-knownをfactにするなど）したりすると、そのサブエージェントからのすべてのエントリーが検証に失敗します。あるいは、フィールド内ではなくトップレベルキーの不一致であれば、気付かれないまま破棄されることもあります。
• 別の状態ファイルやキャッシュファイル（.epistemic-map-state.jsonなど）を作成してはいけません。 すべての状態はEPISTEMIC-MAP.md自体のレンダリング済みテキストに保存され、実行のたびにmerge_epistemic_map.pyによって再度解析されます。状態を別の場所に保存する必要がありそうな場合は、references/schema.mdを参照してください。
• 完全な内容の代わりに、EPISTEMIC-MAP.mdを切り詰めたり、要約したり、プレースホルダーを記載したりしてはいけません。 「合計N件。完全なリストはXを参照」のような記載、「N件中上位K件を表示」のような記載、consolidated.json、backlog.md、またはEPISTEMIC-MAP.md自体ではないその他のファイルへの案内は不可です。このファイルは自己完結しており、マージスクリプトが生成したすべてのエントリーを、ファイルがどれだけ長くなっても記載する必要があります。エントリー数が多いことは、要約する理由にはなりません。そもそもエージェントがエントリーを手作業で保持したり作成したりする必要がない理由については、上記の「相関付けと重複排除」を参照してください。
• 中間の「統合済み」または「マージ済み」の調査結果ファイルを作成してはいけません。 複数の--findings引数を使い、各サブエージェントの一時ファイルをすべて単一のmerge_epistemic_map.py呼び出しに直接渡してください。相関付けはスクリプトが行うため、事前にマージする必要はありません。
• EPISTEMIC-MAP.mdを手作業で作成したり、再構成したりしてはいけません。 書き込みはすべてmerge_epistemic_map.pyを通して行ってください。手作業で編集すると、見た目に一貫性がなくなるだけでなく、次回の実行時に解析に失敗します。
• EPISTEMIC-MAP.md自体に「関連ドキュメント」セクションを追加してはいけません。 リンクは一方向です。AGENTS.md／CLAUDE.mdからこのファイルを参照し、その逆は行いません。
• 相対パスを使ったり、スキャン対象のリポジトリ内に一時ファイルや調査結果のJSONを書き込んだりしてはいけません。 /tmp/...の絶対パスのみを使用してください。merge_epistemic_map.pyは相対パスを一切拒否します。
• 証拠に裏付けられていないエントリー（事実、疑問、仮定）や推論の経緯（リスク）を捏造してはいけません。 確実な事実として断定せず、INFERREDと記してください。また、調査結果を実際より確かなものに見せるために、確信度を黙って引き上げてはいけません。
• openspec/changes/archive/を自動的にクロールしてはいけません。 ユーザーが明示的に指定した場合に限り、特定のアーカイブファイルを読み取ってください。
• サブエージェントが利用できる場合、サブエージェントによる抽出を逐次実行してはいけません。 ソースごとに1つずつ、同時にディスパッチしてください。1ウェーブあたり最大5つです。

象限テスト

候補となるすべての観察事項を、次のトリアージに順番に通します。最初のYESで終了します。

CANDIDATE OBSERVATION
        |
        v
Q1: Backed by evidence (data, contract, test result,
    executed code path, explicit recorded decision)?
        |
   YES -+----------------------------> KNOWN KNOWN (Fact)
        | NO
        v
Q2: Is the gap explicitly raised somewhere (a TODO,
    an open question in a doc, a ticket, an unresolved
    thread)?
        |
   YES -+----------------------------> KNOWN UNKNOWN (Question)
        | NO
        v
Q3: Does the code or docs silently rely on this without
    anyone stating it outright?
        |
   YES -+----------------------------> UNKNOWN KNOWN (Assumption)
        | NO
        v
             (handled separately, see Synthesizing Risks below)
                                    -> UNKNOWN UNKNOWN (Risk)

references/quadrant-test.mdには、各象限の実例と、認識的に見えてもそうではないもの（チームの好み、すでにCONSTRAINTS.mdに記載されている決定済みの事実、用語集の用語など）の振り分け表を含む完全版が記載されています。最初の抽出ウェーブを開始する前に読んでください。

このテストから構造上何が導かれるかに注意してください。事実、疑問、仮定はすべて、サブエージェントが1つのソースを詳しく読むことで見つけられます。一方、リスクはそうではありません。単一のソースにリスクが記載されているなら、それはすでに疑問か仮定に該当します。リスクは全体像を一度に見ることで初めて明らかになるため、同じ抽出ウェーブから得るのではなく、以下で独立したパスを設けています。

ソースの検出

対象となるソースタイプは2つです。

• ドキュメント。 docs/、documents/、README.md などの慣例的なフォルダーを自動スキャンします。検出動作は constraints-extractor と同じです。ユーザーが追加した明示的なパスも受け付けます。デフォルトでは openspec/changes/archive/ を除外します。これは現在の知識ではなく、過去の記録だからです。このスキャンでは、CONSTRAINTS.md、JARGON.md、ARCHITECTURE.md、AGENTS.md／CLAUDE.md、および EPISTEMIC-MAP.md 自体も除外してください。これらは相互参照のために以下で別途読み込むものであり、ソースとして再抽出するものではありません。これらまで含めてしまう広範なドキュメント glob は、循環エントリーや重複エントリー（検証済みの CONSTRAINTS.md の項目にある事実を再「検出」するなど）を生み、すでに把握済みの内容にサブエージェントの作業を費やすことになります。
• コードベース。 プロトタイプでは、文章よりもコードに暗黙知が多く含まれます。ハードコードされたリージョン、// TODO: handle retries、エラーを黙って握りつぶす try/catch、誰も説明していない設定値などです。メインのソースディレクトリ（src/、lib/、app/、またはリポジトリで実際に使われているディレクトリ）を特定し、最上位の各モジュールまたはパッケージを、抽出時にそれぞれ独立したソースとして扱います。

上記のセクションに従い、既存の CONSTRAINTS.md、JARGON.md、ARCHITECTURE.md、および AGENTS.md は最初に読み込んでください。これらは既知の既知事項の種となり、再記述すべきでない内容を示します。この読み込みと、上記のソース検出 glob は互いに独立しています。同じターン内で、順番にではなく、並列／一括のツール呼び出しとして実行してください。 どちらも相手の結果には依存しません。安価で独立した2つの処理を直列化しても、メリットはなく遅延が増えるだけです。

任意のインタビューパス。 元の作成者にまだ連絡できる場合は、相関付けの後に短く的を絞った質問フェーズを有効にするため、--interview を指定します。デフォルトでは無効です。実行時には作成者がすでにいない可能性があるため、有用なマップを作成するのにインタビューセッションを必須としないでください。

事実、質問、仮定の抽出

サブエージェントへのプロンプトを1つでも作成する前に、references/schema.md を最初から最後まで読んでください。 すべてのサブエージェントのタスク指示には、そのファイルに記載された正確な JSON 形式を直接引用して含める必要があります。最上位キーの entries、フィールド名（statement、evidence、impact、confidence。observation や別の同義語は使用しない）、およびハイフン付きの known-known／known-unknown／unknown-known という正確な象限の値を含めてください。fact や question のような短縮形は使用しないでください。このファイルにある要約からスキーマを再構成したり、記憶に頼ったりしないでください。ここで言い換えると、サブエージェントの出力でフィールド名が変更されたり、象限名が短縮されたりしやすくなります。merge_epistemic_map.py は、近似した形式ではなく、記載されたスキーマに対して厳密に検証します。

ソースごとにサブエージェントを1つずつ起動します（ドキュメントごとに1つ、最上位のコードモジュールごとに1つ）。このスキルファミリーの他の部分と同様に、1回のウェーブで同時に実行するのは最大5つまでです。各サブエージェントは、ソース内のすべてを Q1／Q2／Q3 テストにかけ、Q1 から Q3 の象限に該当する候補だけをフラットなリストで報告します。このウェーブではリスクは対象外です。1つのファイルだけを見るサブエージェントには、システム全体に関わる真のリスクと、局所的な異常を見分ける方法がありません。

すべての事実、質問、仮定には、少なくとも1つの根拠の参照先が必要です。参照先には、プロジェクトのルートからの相対パス（絶対パスではありません）、行範囲またはセクション、および該当箇所の短い引用または言い換えを含めてください。根拠がなければ、エントリーもありません。これは constraints-extractor と同じ考え方です。曖昧さは問題ありませんが、裏付けのない主張は認められません。

サブエージェントは、作業用の抽出結果を絶対パスのみ（例：/tmp/epistemic-mapper/<source-id>.json）に書き込みます。相対パスは使用しないでください。相対パスではリポジトリの作業ディレクトリを基準に解決され、ルートに不要な JSON ファイルが残ります。相対パスが使われそうな場合は拒否し、再度依頼してください。

相関付けと重複排除

波の調査結果を scripts/merge_epistemic_map.py でマージします。このスクリプトは、ID の割り当て、references/schema.md のエイリアステーブルに基づくカテゴリスラッグの正規化、複数のソースにまたがる重複の集約、並べ替えといった機械的な処理を担当します。これは判断を要する作業ではありません。手作業で行ったり、事前にマージしたりしないでください。

すべてのスクラッチファイルを直接渡して、1 回だけ実行します。 すべてのサブエージェントのスクラッチファイル（すべての波の分）とリスク統合ファイルを、複数の --findings 引数として、スクリプトの 1 回の実行 に渡します。

python3 scripts/merge_epistemic_map.py \
  --findings /tmp/epistemic-mapper/doc-1.json /tmp/epistemic-mapper/doc-2.json ... /tmp/epistemic-mapper/risks.json \
  --output-dir /absolute/path/to/repo/root

手作業で事前にマージする手順も、「統合済み」ファイルを中間生成する必要もありません。スクリプトが各調査結果ファイルをディスクから直接読み込み、重複を自動的に排除するからです。つまり、エントリーの量を調整役のエージェントが自分のコンテキスト内に抱えたり、手作業で作成したりする必要はありません。13 件のソースドキュメントから候補が合計 106 件生成される場合でも、スクリプトが小さなファイルを 14 個読み込んで出力ファイルを 1 つ書き出すだけで、調整作業の量は候補が 4 件のソース 2 件の場合と変わりません。書き出す量が「多すぎる」と感じるなら、スクリプトを生のスクラッチファイルに対して直接実行していないということです。いったん止めて、要約するのではなく、その方法で実行してください。

マージ中に、各エントリーに確信度の段階を割り当てます。

• CONFIRMED — 2 つ以上の独立したソースが一致しています。
• INFERRED — 単一のソースに基づき、妥当な解釈ができます。
• CONFLICTING — ソース間で意見が食い違っています。誤った中間的な見解に平均化せず、両方の解釈を明示してフラグを立ててください。Facts 象限の CONFLICTING エントリーは、それだけでエスカレーションに値する矛盾です。同じ API のレート制限について、2 つのドキュメントで異なる値が示されていること自体が調査結果です。

リスクの統合

相関付けの後、統合された全体像を対象に、ソースごとではなくすべてを一度に見る専用のパスを 1 回実行します。全体をまとめて見たときにだけ現れるパターンを探してください。

• 3 つの別々のモジュールが特定の動作をすると仮定している依存関係で、コードベースにもドキュメントにも、その動作を裏付けるものがないもの。
• フォールバックがどこにも記載されていない単一のベンダー、リージョン、または認証情報。特に、それに関連する Assumptions がすでに複数集まっている場合。
• 外部呼び出しのエラー処理がない、文書化されたロールバック手順がない、所有者も期限もない「一時的な」決定など、引き継ぎの失敗でよく見られる構造的なパターンが、このプロジェクトにも存在するケース。ここで誰かが指摘しているかどうかは問いません。

どのソースにも Risk が明記されていないため、根拠の引用は適用されません。代わりに、推論の経路を記述してください。どの観察事項を組み合わせるとそのリスクが示されるのか、また、なぜその組み合わせが個々の観察事項より重要なのかを説明します。ここは、引用ではなく統合と判断が求められる唯一の象限です。存在しない引用を捏造せず、そのことを明確に述べてください。

リスクにも、5 つの正式なカテゴリスラッグのいずれかが必要です。新しいスラッグは決して作成しないでください。 統合されたリスクは本質的に複数の領域にまたがるため（それが、特定のソースに紐づけて登録する Fact ではなく Risk である理由です）、references/schema.md にある 5 つのカテゴリのどれよりも細かいラベルがふさわしいと感じることがよくあります。しかし、その誘惑には負けないでください。カテゴリフィールドが答えるのは「影響が及ぶのはどこか」であり、「どのようなリスクパターンか」ではありません。3 つの成果物にまたがるスケジュール依存の連鎖は、新しい schedule-cascade-risk カテゴリではありません。約束の未達が外部に影響するなら business-scope、内部のボトルネックなら team-process です。実際に影響が及ぶ場所に基づいて、最も近い既存のスラッグを選び、具体的な仕組みは、詳細さを記述するための statement と reasoning のテキストに記載してください。merge_epistemic_map.py は、作成されたカテゴリを推測することを拒否します。この状況の具体例については、references/schema.md の実例を参照してください。

バックログの作成

merge_epistemic_map.py は、エピステミック・バックログを自動的に生成します。四象限と深刻度に基づいて優先順位を付けた、3～5件のアクション項目です（未検証の盲点は、把握済みの未解決の問いよりも新しいチームにとって危険なため、通常はリスクと前提が問いよりも優先されます）。バックログは常に、EPISTEMIC-MAP.md 自体の ## Epistemic Backlog セクションに配置されます。

独立した backlog.md ファイルは存在せず、今後も作成してはいけません。 作成したり、参照したり、実際のチェックリストの代わりに「backlog.md を参照」と書いたりしないでください。バックログをチェックリストではなく実際のチケットにする必要がある場合は、利用可能であれば、上位の項目をチケット作成スキルに引き継ぐことを提案してください。ただし、それによって作成されるのはチケットであり、Markdown ファイルではありません。また、これはあくまで提案であり、自動的に行うことではありません。提案が断られた場合でも、EPISTEMIC-MAP.md 内のチェックリストは常にそれ単体で完結しています。

EPISTEMIC-MAP.md のプレビューと書き込み

EPISTEMIC-MAP.md は自己完結した単一ファイルで、通常の Markdown です。フロントマターも、非表示のブロックも、付随する状態ファイルもありません。マージ時に往復処理が必要なすべてのフィールド（id、category、confidence、evidence、impact、history、severity、first-seen date）は、各エントリのレンダリングされた行に直接含まれています。エントリごとの正確な形式については、references/schema.md を参照してください。次回の実行時には、merge_epistemic_map.py が同じテキストを状態として解析し直します。これは、すでに constraints-extractor が採用している方法です。ファイルが2つあったり（または、表示されるブロックと非表示のブロックがあったり）すると、引き継ぎ用の成果物をコピー、移動、レビューする際に片方が取り残されたり、理由もなく同じ内容が二重に含まれたりします。このスキルの初期ドラフトは、まさにそれを YAML フロントマターブロックで行っており、情報をまったく増やさずにファイルサイズをおよそ2倍にしていました。再導入しないでください。

このファイルを書き込んだり変更したりする正当な方法は、merge_epistemic_map.py だけです。 EPISTEMIC-MAP.md を直接、手作業で作成したり構成し直したりしないでください。見出しも、エントリ内の1行も例外ではありません。調査結果は references/schema.md に従ってスクラッチ JSON に書き込み、スクリプトを実行してください。スクリプトは実行のたびに、解析し直した内容からファイル全体を再生成します。手作業による編集は再実行後に残らないだけでなく、意図的に次回の実行時にファイル全体の解析エラーを引き起こします。上記の「絶対にしてはいけないこと」を参照してください。ファイルの構成はスクリプトが生成する内容そのもので、Facts、Questions、Assumptions、Risks、Epistemic Backlog 以外は含まれません。タスクで別のセクション（相互リンクの注記、要約ファイルなど、このリストにないもの）が必要に思える場合は、ファイルに追加するのではなく、会話の中でその旨を伝えてください。

このスキルファミリーの他のものと同じ慣例に従い、既存ファイルへの小さな更新であっても、書き込む前に必ずプレビューしてください。再実行時、スクリプトは既存ファイル内のレンダリング済みエントリから直接以前の状態を読み取ります（ほかに読み取り元はありません）。そして、次の項目を記録します。

• 昇格 — 証拠が得られた Assumption または Question は別の区分に移動し、エントリには History (DATE): was -> became — reason の行が追加されます。最新のものだけでなく、エントリの履歴行はすべて保持されます。
• 解決 — 回答が得られた Question、または修正された Risk は、ひそかに削除せず、短い注記を添えて resolved と記録します。以前不確かだったことに関する組織の記憶には価値があります。
• 却下 — 調査の結果、該当しないとわかった Risk は、同じ理由で、判断の根拠を残したまま dismissed と記録します。

状態をひそかに上書きしないでください。実行時に新規または変更されたエントリが1つも見つからなかった場合は、ファイルを充実しているように見せるために内容を水増しせず、エグゼクティブサマリーでその旨を明確に伝えてください。EPISTEMIC-MAP.md が存在していても、merge_epistemic_map.py 自身がレンダリングする内容と一致しない場合（手作業による編集、必要なフィールドが欠けた見出し、このスキルの以前のバージョンで使われていた古いフロントマター形式のファイルなど）、スクリプトは以前の状態を推測して昇格履歴をひそかに失うことを避けるため、実行を拒否します。そのエラーは回避策を講じず、ユーザーに伝えてください。

AGENTS.md / CLAUDE.md への相互リンク

これは「ファイルはスクリプトが管理する」という原則の唯一の例外です。EPISTEMIC-MAP.md がすでに書き込まれ、プレビューされた後に、別のファイルに対して一度だけ文章を手動で編集します。EPISTEMIC-MAP.md 自体の生成には一切触れません。

対象の場所に AGENTS.md または CLAUDE.md がある場合、「Related Documentation」セクション（または同等のセクション）がすでにあり、EPISTEMIC-MAP.md を参照しているか確認します。参照がなければ、ファイルがすでに使っているスタイルに合わせて、1行の参照を追記することを提案します。これは、jargon-extractor が JARGON.md にリンクし、constraints-extractor が CONSTRAINTS.md にリンクする方法に倣います。これは通常の文章編集であり、補助スクリプトではありません。1回の存在確認であり、大量の並べ替えや重複排除ではないため、継続的な機械処理を正当化する作業はありません。

AGENTS.md／CLAUDE.md はエージェントとのやり取りのたびに読み込まれるため、そこに置かれたポインターは受動的な脚注ではありません。エージェントが EPISTEMIC-MAP.md 自体を開くかどうかにかかわらず、ファイルが読み込まれるたびに表示されます。「見つけられる」だけでなく、「実際に参照する」よう促す文面にしてください。

- **EPISTEMIC-MAP.md**: What's proven, what's assumed, and what's still unknown about this project; most relevant during handoff.
  _(Check this before making changes in an area flagged as an open Question or Assumption — treat an entry there as something to verify, not something to rely on)_

リンクは一方向です。上記の「NEVER リスト」のルールを参照してください。この手順では AGENTS.md／CLAUDE.md から EPISTEMIC-MAP.md にリンクします。逆方向のリンクは作成しません。

参照ファイル

• references/quadrant-test.md — 各象限の具体例と、判断が微妙なケースの振り分け表（トリアージ判定そのものは上記のフローチャートを参照）。抽出前に読んでください。
• references/template.md — 新規ファイル作成時に使用する EPISTEMIC-MAP.md の完全なひな形。
• references/schema.md — サブエージェントがスクラッチファイルに書き込む JSON の形式、カテゴリの別名テーブル、merge_epistemic_map.py が想定する形式。サブエージェントをディスパッチする前に必ず読んでください。フィールド名と象限の値を言い換えずにそのままサブエージェントへのプロンプトに引用してください。上記の「事実、疑問、仮定の抽出」を参照してください。