fable-research

Fable Research

モデルの記憶ではなく、最新の一次情報を使って、実装に影響する外部の事実を確認します。

ミッション

リサーチはリンク集めではありません。出力は、リポジトリが使用する正確なバージョン、環境、または契約に結び付いた、意思決定に使える記述でなければなりません。

以下の場合に使用する

• SDK／API のシグネチャ、制限、デフォルト値、ライフサイクルの意味、または互換性が変更されている可能性がある場合；
• 設計が現在のクラウド／プロバイダーの動作に依存する場合；
• リポジトリで固定されているバージョンが、最新のドキュメントとは異なる可能性がある場合；
• 複数の公式情報源の内容が一致しない場合；
• エラーの原因が、文書化された破壊的変更または非推奨化の可能性がある場合；
• 標準／RFC／セキュリティ要件を正確に解釈する必要がある場合。

以下の場合は使用しない

• 事実がリポジトリ内に限られる場合（fable-discover）；
• 実装の根拠がすでにあり、実行だけが必要な場合（fable-execute／fable-tdd）；
• 外部の主張によって判断が変わらない、一般的なブレインストーミングの場合。

リサーチの分類

まず質問を分類します。

質問の種類	最適な一次情報	追加のリスク
API シグネチャ	バージョン付きの公式ドキュメント＋ソース／型定義	ドキュメントは最新を示している一方、リポジトリでは古いバージョンが固定されている場合がある
ランタイムの動作	公式ドキュメント＋上流の実装／テスト	マーケティング資料では細かな動作が省略されている場合がある
互換性	リリースノート／変更履歴＋バージョンマトリックス	推移的依存関係による制約
標準／プロトコル	規範的な仕様／RFC	例が非規範的な場合がある
クラウド／製品の制限	ベンダーの最新ドキュメント	リージョン／ティア／アカウントによる違い
セキュリティガイダンス	公式のセキュリティドキュメント／アドバイザリー	古いブログの要約
非推奨化／移行	移行ガイド＋リリースノート	旧 API と新 API が併存している場合がある

手順

ステージ 1 — タスクを回答可能な主張に分解する

広範な依頼を、設計に影響し得る最小単位の外部主張に分解します。

悪い例：「新しい SDK を調査する。」

良い例：

• バージョン 4.2 では、ストリーミングのツール呼び出しデルタが公開されていますか？
• それを有効にするパラメーターはどれですか？
• コールバックの順序は保証されていますか？
• 必要なランタイムの最小バージョンはいくつですか？

ステージ 2 — リポジトリの実情に合わせる

最新のドキュメントが該当すると判断する前に、以下を記録します。

• 実際に使用されているパッケージ／バージョン；
• ランタイム／言語のバージョン；
• 該当する場合、関連する機能フラグ／ティア／リージョン；
• リポジトリが生成された型、または公開契約を変更するラッパーを使用しているかどうか。

ステージ 3 — 情報源の優先順位を適用する

入手可能な場合は、次の順に優先します。

1. 規範的な仕様または公式のバージョン付きリファレンス；
2. 公式の上流ソース／型定義／テスト；
3. 公式のリリースノート／移行ガイド／アドバイザリー；
4. 該当バージョン向けに作成されたベンダーの例；
5. 手掛かりとしての二次情報のみ。

検索結果の出典不明のスニペットを、最終的な根拠として使用してはいけません。

ステージ 4 — バージョンと情報源の矛盾を解消する

最新のドキュメントが固定されたパッケージと一致しない場合：

• 固定されたバージョンのバージョン付きドキュメント／リリースノート／ソースを確認します；
• 相違点を明示します；
• 古いロックファイルに最新の構文を、説明なしに推奨してはいけません。

2 つの公式情報源が一致しない場合は、該当バージョンの実行可能な実態により近い方を優先し、矛盾について報告します。

ステージ 5 — 事実と解釈を分ける

以下を記録します。

• 事実：情報源が立証している内容；
• 適用可能性：それがこのリポジトリ／バージョンに当てはまる理由；
• 解釈：設計にとっての意味；
• 確信度：実測済み／強く裏付けられている／未解決。

ステージ 6 — 判断の根拠が揃ったら終了する

設計に不可欠な外部主張がすべて解決し、次のアクションが安全になったら、調査を続けないでください。

判断ルール

• モデルの学習後に変わった可能性がある事実は、記憶に頼らず検証してください。
• ドキュメントにバージョンの記載がなく、リポジトリで古いバージョンが固定されている場合は、そのバージョンに対応するソース、型定義、変更履歴を確認してください。
• 公式クイックスタートと規範的なリファレンスが矛盾する場合、食い違いを曖昧にせず、対象の動作をどちらが規定するのか判断してください。
• 動作がアカウント、プラン、リージョンに依存する場合は、その依存関係を明記し、普遍的な主張を避けてください。
• 一次ソースが入手できない場合は、証拠の不足を報告し、次善の情報源として上流のコード、型定義、テストを使用してください。不足しているパラメーターを決して捏造しないでください。
• 回答によってアーキテクチャが変わる場合は fable-plan に引き継いでください。制約の明確な実装契約を確認するだけの場合は、fable-tdd または fable-execute に引き継いでください。

不変条件

• 重要な外部情報の主張には、すべて出典が必要です。
• 出典の適用可能性には、URL の信頼性だけでなく、バージョンとコンテキストも含まれます。
• 引用やシグネチャは短く正確に保ち、結論はエージェント自身の言葉で記述します。
• アクセス可能な一次ソースより二次ソースを優先しません。
• 矛盾する証拠は、解決されるまで明示したままにします。

失敗の分類

情報の鮮度に関する失敗

出典は公式ですが、古いか非推奨です。バージョン別または最新の資料とリリース履歴を確認してください。

バージョンの不一致

リポジトリとドキュメントで説明されているバージョンが異なります。ロックファイルやパッケージのメタデータと照合してください。

権威性の不一致

ブログやサンプルが規範的なドキュメントまたは上流のソースと矛盾しています。信頼性の低い出典の優先度を下げてください。

コンテキストの不一致

主張がリージョン、プラン、ランタイム、プラットフォーム、または機能フラグによって異なります。結論の適用範囲を明確にしてください。

解釈の曖昧さ

出典は明確ですが、リポジトリにどう適用されるかは明確ではありません。調査で答えが得られたかのように装わず、未解決の設計上の疑問を fable-plan に引き継いでください。

アンチパターン

• 検索エンジンにシグネチャを尋ね、結果のスニペットをそのままコピーする。
• 固定されているバージョンを確認せず、最新のドキュメントを引用する。
• 意思決定に役立つ結論を示さず、リンクを大量に集める。
• API は「おそらく変わっていない」と考え、モデルの記憶に頼る。
• 出典が適用される理由を説明せずに引用する。
• 公式ソース間の不一致を隠す。
• 重要な主張がすべて解決した後も調査を続ける。

調査パケット／引き継ぎ

Question:
Repository version/context:
Source-backed facts:
- fact → primary source → applicability
Conflicts/version deltas:
Interpretation for implementation:
Confidence / unresolved:
Recommended next Skill:

完了条件

以下を満たしたとき、調査は完了です。

• リポジトリの実際のコンテキストにおいて、対象の外部情報に関する主張に答えている。
• 証拠が一次ソースに基づいているか、一次ソースがないことを明示している。
• バージョンの不一致を解消している。
• 過剰な主張をせずに、実装または設計への影響を示している。
• 重要なパラメーターや意味に曖昧さが残っていない。

段階的に参照するリソース

• 詳細ガイド：references/source-reconciliation-playbook.md
• 既存の優先順位：references/primary-source-hierarchy.md
• 例：examples/research-api-specs.md