fable-discover

Fable Discover

設計や編集を誰かが決定する前に、未知のコードパスについて、信頼できる最小限のメンタルモデルを構築します。

ミッション

ディスカバリーは「大量のファイルを読むこと」ではありません。不確実性を減らすことです。

このスキルは、次の担当者がリポジトリを再調査せずに判断できるだけの根拠を残しつつ、探索が考古学的な調査になる前に止めます。

次の場合に有効化

• エントリーポイント、所有者、実行フローがわからない場合；
• 依頼が未知のパッケージ／サブシステムにまたがる場合；
• 生成コード、プラグイン、ランタイム設定、キュー、ジョブ、依存性注入によって、実際の実行パスが変わる可能性がある場合；
• ユーザーが動作を説明しているものの、どこに実装されているかを示していない場合；
• リポジトリについての以前の想定が覆された場合。

次の場合は有効化しない

• 範囲が明確な編集内容と対象ファイルがすでにわかっている場合；
• 作業が外部 API／バージョンの調査のみの場合（fable-research）；
• 既存のチェックを実行するだけのタスクの場合（fable-verify）。

状況の分類

検索を始める前に、未知の内容を分類します。

未知の内容	最初に探す根拠	よくある落とし穴
トポロジー	マニフェスト、ワークスペース設定、パッケージ境界	ルートパッケージがランタイムを所有していると思い込む
エントリーポイント	CLI／サーバー／ジョブ／プラグインのブートストラップ	名前が似ているヘルパーから調査を始める
実行パス	呼び出し、ハンドラー、イベント、データ遷移	ランタイムから到達可能であることを確かめずにインポートをたどる
設定	環境変数／スキーマ／デフォルト／機能フラグ	本番環境で上書きされているのにデフォルトだけを読む
生成される動作	ビルドスクリプト、コード生成の出力、生成されたマニフェスト	ソースではなく生成済みの出力を編集する
プラグイン／拡張機能のパス	登録、検出、ローダーの契約	grep で直接のインポートが見つからず、動的読み込みを見落とす
永続化／データパス	リポジトリ、スキーマ、トランザクション、キュー	副作用を確認する前にサービス層で調査を止める
テストアーキテクチャ	ハーネス、フィクスチャ、テストのエントリーポイント	テストがユーザーの実行するものと同じ成果物を検証していると思い込む

ディスカバリープロトコル

ステージ 1 — 未知の内容を明確にする

答えによって計画が大きく変わる質問を 2～7 個書き出します。それぞれに load-bearing または nice-to-know のラベルを付けます。

例：

• このリクエストを受け取るプロセスはどれですか？
• パッケージのソースを直接実行しますか、それとも dist/ から実行しますか？
• このプラグインはどこで登録されますか？
• どのストレージ境界で状態が確定しますか？

質問を明確にするまでは、広範囲な検索を始めないでください。

ステージ 2 — リポジトリのトポロジーを把握する

まずプロジェクトの指示とマニフェストを読みます。次の項目を特定します。

• ワークスペース／パッケージのルート；
• ビルド／テストコマンド；
• 生成ディレクトリ；
• ホスト／プラグインのマニフェスト；
• ソースと配布用エントリーポイント；
• 設定のソース；
• 関連する所有者の境界。

ステージ 3 — 実際のパスをたどる

観測可能なエントリーポイントから始め、具体的なシンボル／イベントをたどって対象の動作に進みます。

各ステップについて、次の内容を記録します。

• ファイル／シンボル；
• このステップに到達できる理由；
• 入力／出力の契約；
• 副作用または状態遷移；
• 確実性：[measured]、[inferred]、または [unresolved]。

インポートの連鎖だけでは、コードが実行される証拠になりません。

ステージ 4 — 静的な根拠だけでは不十分な場合に限り、ランタイムを調査する

名前を付けた質問に答えるため、安全な読み取り専用のランタイム観測を行います。ログ、ヘルプ出力、ルート一覧、テスト検出、ビルドメタデータ、または範囲を絞った再現を利用します。

好奇心を満たすためだけに、本番環境の状態を変更しないでください。

ステージ 5 — 矛盾を解決する

観測された根拠が現在のモデルと矛盾する場合は、ただちにモデルを更新します。以前の調査が筋の通ったものに見えるからといって、古い仮説を維持しないでください。

ステージ 6 — 意識的に調査を止める

すべての load-bearing の質問について、次のいずれかを満たした時点で終了します。

• 根拠を添えて回答済みである；
• 影響と次のスキルを明記して、未解決としている。

nice-to-know の質問は引き継ぎを妨げません。

判断ルール

• 不明点が外部情報に関するもので、時間とともに変化する場合は、モデルの記憶から推測せず、その質問を fable-research に引き継ぎます。
• 編集内容が限定され、設計上の判断が残っていない場合は、fable-execute に引き継ぎます。
• 複数のコンポーネントやリスクを調整する必要がある場合は、fable-plan に引き継ぎます。
• 検索結果からコードが自動生成されたものと思われる場合は、編集を推奨する前に、生成ツールまたは信頼できる唯一の情報源を特定します。
• 境界で直接インポートが見えなくなった場合は、登録テーブル、イベントバス、依存性注入、プラグイン検出、リフレクション、コード生成、ランタイム設定を調べます。
• テストとランタイムの動作が食い違っているように見える場合は、両方の経路を記録し、テストハーネスが正しいと決めつけないでください。

不変条件

• ユーザーが明示的にタスクを変更しない限り、調査は読み取り専用です。
• 結論の根拠となる重要な点は、すべてリポジトリまたはランタイムの具体的な証拠に基づきます。
• 推論には推論であることを明記します。
• 検索範囲を広げる場合は、未解決の疑問に照らしてその理由を示します。
• 手作業で保守されていることを確認できない限り、生成された出力を正規のソースとして扱いません。

失敗の分類

検索漏れ

シンボルが見つからない場合は、別名、生成された名前、動的読み込み、レジストリ、イベントディスパッチ、リフレクション、コンパイル済み出力、パッケージ境界を確認します。

誤った経路

関連性がありそうなファイルが、実際のエントリーポイントから到達できない場合は、実証済みのランタイムまたはブートストラップの境界に戻ります。

環境の曖昧さ

動作が環境変数、フラグ、設定に依存する場合は、優先順位と有効な設定を特定します。デフォルト値をランタイムの事実として報告しないでください。

ソースとアーティファクトの不一致

テストやコマンドが、編集したソースではなく、ビルド済みまたは古いアーティファクトを実行している場合は、両方の経路を記録します。これが失敗の繰り返しにつながった場合は、fable-recover に引き継ぎます。

重要な不明点が残っている

曖昧なままにしないでください。調査担当に引き継ぐか、未解決の判断事項を明示的に報告します。

アンチパターン

• 「背景を把握するため」にパッケージ内の全ファイルを読むこと。
• ファイル名をアーキテクチャとして信頼すること。
• grep の出現頻度を重要度とみなすこと。
• ランタイムで到達可能かを確認せずにインポートを追うこと。
• ビルド、コード生成、プラグイン登録を無視すること。
• [inferred] ラベルを付けずに仮定を報告すること。
• 計画上の判断がすでに安全に行える段階を過ぎても、調査を続けること。

エビデンスパケット／引き継ぎ

簡潔なパケットを作成します。

Target:
Load-bearing questions:
Measured facts: file:symbol → fact
Execution path: entry → ... → side effect
Configuration/runtime notes:
Generated/plugin boundaries:
Unresolved questions + consequence:
Recommended next Skill:

完了条件

次の担当者が以下を説明できる状態になれば、調査は完了です。

• 実行がどこから始まるか。
• どの経路が対象の動作に到達するか。
• 重要な契約や状態境界は何か。
• 実測した事実と推論した事実は何か。
• 何が未解決か。
• 残っている未解決点が次のアクションを妨げるかどうか、その理由。

段階的なリソース

• 詳細なプレイブック：references/repository-investigation-playbook.md
• 既存のエビデンスプロトコル：references/evidence-gathering-protocol.md
• 例：examples/codebase-inspection.md