fable-learning

Fable Learning — 失敗の教訓と知識統合エンジン

エンジニアリングの会話、エージェントの実行履歴、セッションで明らかになった事実を、Failure-lessons/、agent-kernel ルール、gbrain チャンク、複合ソリューションドキュメント（docs/solutions/）、および移植可能なプレイブックに保存される、長期的に活用できるプロジェクト知識に変換します。

$$\text{セッションで明らかになった事実} \xrightarrow{\text{事実の抽出}} \text{失敗、修正、不変条件、テスト} \xrightarrow{\text{蒸留と厳密化}} \text{Failure-lessons/ + agent-kernel + gbrain} \xrightarrow{\text{進化}} \text{プレイブックとスキル}$$

---

ミッション

ミッションステートメント：このセッションを長期的に活用できるプロジェクトの教訓に変換する

このセッションには、会話が終わっても失われるべきではないエンジニアリング知識が含まれています。

あなたのタスクは、完了した作業から再利用可能な教訓を抽出し、長期的に活用できるプロジェクト知識として保存することです。

単なるセッションの要約を作成してはいけません。
変更点を列挙するだけではいけません。
失敗、発見、修正、アーキテクチャ上の決定、デバッグの知見、テスト戦略、実装ミスを、今後のコントリビューターやコーディングエージェントが活用できる、再利用可能なエンジニアリングの教訓に変換してください。

基本的な目標は次のとおりです。

エンジニアリング上のミスは、一度だけコストを払う。
その後は、プロジェクトがそのミスを記憶しているべきです。

---

次の場合に有効化

• 完了済みまたは進行中のセッションから、得られた知見、検証済みの修正、またはパターンを抽出するとき。
• ユーザーが /learn、learn、convo-learn、fable-learning、「何を学んだか？」、「学びを抽出して」、「学んだことを保存して」、「セッションを長期的に活用できる教訓に変換して」を実行したとき。
• 重大なバグ、テストのリグレッション、または設定上の障害を解決し、再発防止のための不変条件を確立するとき。
• リポジトリの Failure-lessons/ ナレッジベースを作成または更新するとき。
• ユーザーからの修正、確認、エスカレーションを、トレーニング後のシグナルとして記録するとき。
• 関連する問題と解決策のペアを3つ以上統合し、agent-kernel プレイブックを作成するとき。
• fable-skill-creator を使い、会話から新しい移植可能なスキルパッケージを作成するとき。
• セッション完了時（Stop／SessionEnd フックイベント）にヘッドレスで実行し、学習チャンクを記録するとき。

---

次の場合は有効化しない

• トランスクリプトを分析せずに、コード差分またはプルリクエストをレビューするとき（fable-review）。
• アプリケーションの機能またはバグ修正がテストに対して正しく動作するか検証するとき（fable-verify）。
• ユーザーの好みや静的な環境情報をメモリに保存するとき（fable-memory）。
• 定量的なベンチマークを実施したり、プロンプトモデルを比較したりするとき（fable-eval）。

---

状況の分類

呼び出しパターン	モード	主な保存先	アクションと深度	出力アーティファクト
ユーザーが失敗の教訓、事後検証、または根本原因の体系化を求める	FAILURE_LESSONS	Failure-lessons/ + agent-kernel + gbrain	22ステップの失敗抽出とリグレッションの関連付けをすべて実施	Failure-lessons/*.md + レポート
明示的なセッション ID またはトランスクリプトファイル	ANALYZE	Failure-lessons/ + agent-kernel + gbrain	4カテゴリすべての抽出と統合を実施	構造化された Markdown レポート
短いセッションまたは --depth lightweight	QUICK	agent-kernel + gbrain	上位5つの原子的な $L3+$ ルール	ターミナル出力
解決済みの重大なバグまたはハーネスの問題	COMPOUND	docs/solutions/ + CONCEPTS.md	原子的な問題解決ドキュメントを1件作成	docs/solutions/YYYY-MM-DD-<slug>.md
「これからスキルを作って」または --compile	COMPILE	skills/<name>/	抽出をすべて実施し、fable-skill-creator を使って SKILL.md を作成	スキルパッケージ
「何を学んだか？」または --recall	RECALL	ターミナル出力／要約	gbrain と agent-kernel に問い合わせて統合	対話型ダイジェスト
セッション後フック（Stop／SessionEnd）	HEADLESS	agent-kernel + gbrain	フェイルソフトの安全対策を備えた自動バックグラウンド抽出	Documentation complete／skipped

---

プロトコル

22ステップの失敗の教訓抽出プロトコル

1. 利用可能な学習ツールを確認する

ホスト環境で実際に利用できるツールを確認します。

• /learn、learn
• gsd:extract-learnings
• /convo-learn、/fable-learning
• agent-kernel remember
• gbrain remember

ルール：

• 実際に利用できるツールを確認します。利用できないコマンドを実行したふりをしてはいけません。
• 適切な場合は、同等の利用可能なツールを使います。
• エージェントのメモリツールを利用できない場合も、リポジトリのドキュメント（Failure-lessons/）を永続的な信頼できる情報源とします。

2. 関連するセッション全体を振り返る

何かを書く前に、実際に何が起きたのかを再構成します。会話、実装の履歴、差分、テスト、ツールの出力、レビューのフィードバック、現在のリポジトリの状態を確認します。 最終的に成功した結果だけでなく、次のような知見も抽出します。

• 発生したバグや誤った思い込み
• 失敗したアプローチやデバッグで明らかになったこと
• 根本原因やアーキテクチャ上の弱点
• 実装上の修正やリグレッション
• エッジケースやテストの失敗
• レビュアーの指摘やツールの制約
• API コントラクトの問題やパフォーマンス上の問題
• データの問題やセキュリティ上の問題
• 運用上の問題や後方互換性の問題
• 判断が覆された箇所や、完了を早まって宣言した箇所
• 特にうまくいき、標準的なプラクティスにすべきこと

履歴を取り繕ってはいけません。 失敗したアプローチには、最終的な修正より価値のある教訓が含まれていることがあります。

3. 事実と仮説を分ける

重要な知見ごとに、次のように区別します。

• Confirmed root cause：コード、ログのトレース、または再現可能なテストによって証明されている。
• Strongly indicated cause：強い相関に裏付けられており、非常に可能性が高いが、メカニズムが完全には特定されていない。
• Open hypothesis：妥当な説明ではあるものの、さらなる検証が必要。
• Unknown：原因がまだ特定されていない症状を、正直に記録する。

推測を過去の事実として扱ってはいけません。

4. プロジェクトの障害教訓ナレッジベースを作成または更新する

次のディレクトリを使用します。

Failure-lessons/
├── README.md                     # Knowledge base principles, triggers, and maintenance rules
├── lessons-index.md              # Compact registry table and "Rules We Now Enforce"
├── testing-and-verification.md   # Regression test mappings, oracle proofs, and test strategies
└── <topic-specific-lessons>.md   # Lessons grouped by failure domain (e.g. state-management.md)

Failure-lessons/ が存在しない場合は作成します。リポジトリに同等の既存の場所がある場合は、明示的な指示がない限り、既存の慣例を維持します。不要な競合ナレッジシステムを作成してはいけません。

トピックドキュメントの例： authentication.md、state-management.md、database-integrity.md、api-contracts.md、background-jobs.md、caching.md、artifact-lifecycle.md、performance.md、frontend-state.md、deployment.md、testing.md、security.md、data-quality.md、model-lineage.md、observability.md。 テンプレートに合わせるためだけに、空のファイルを作成してはいけません。

5. チケット番号ではなく、障害の種類ごとに整理する

チケット番号や一時的な参照に基づくドキュメント構成は避けます。

• ❌ Bug #143、Bug #188、Issue from Tuesday、Problem we fixed in PR #92

安定した、内容を表す障害の種類を優先します。

• ✅ Non-atomic resource publication
• ✅ Validation logic duplicated across entry points
• ✅ Background jobs without terminal-state guarantees
• ✅ Client and server disagreeing about API semantics
• ✅ Regression tests that never reproduced the original failure

6. 標準的な障害教訓のスキーマを使用する

意味のある教訓はすべて、次の14セクションのスキーマに従います。

## [Failure / lesson name]

### Context
Where this class of problem appeared.

### What happened
Short factual description.

### Observable symptom
What engineers or users actually saw.

### Impact
Why the failure mattered.

### Incorrect assumption
What the system or implementation implicitly assumed that turned out to be wrong.

### Root cause
State one of: Confirmed | Strongly indicated | Unresolved. Then explain the evidence.

### Why the architecture allowed it
Explain the deeper system condition that made the failure possible.

### Fix
Describe the implemented solution at the appropriate abstraction level. Avoid documenting only a one-line patch if the meaningful fix was architectural.

### Verification
Document how the fix was proven. Reference real tests, commands, fixtures, or reproducible experiments.

### Prevention rule
Write the invariant future implementations should preserve.

### Reusable lesson
Explain where else this lesson applies.

### Related code
Reference stable modules, symbols, or paths where useful.

### Related tests
Reference relevant regression or integration tests.

### Related lessons
Cross-link other entries when applicable.

### Status
One of: Resolved | Partially mitigated | Unresolved | Superseded.

7. バグの背後にある教訓を抽出する

表面的な要約（「X の検証を忘れた」）だけで終わらせてはいけません。 次の点を確認します。

• なぜ検証を忘れることができたのでしょうか？
• 同じ不変条件を複数のエントリーポイントで独立して実装していたのでしょうか？
• コントラクトが不明瞭だったり、障害の兆候が隠れていたりしたのでしょうか？
• テストの範囲が狭すぎたり、状態が重複していたりしたのでしょうか？

次の内容を変換します。

「エンドポイント B でテナント検証が抜けていた。」 次の内容に変換します。 「ドメインの不変条件を複数のエントリーポイントで独立して実装すると、実装にずれが生じます。すべてのエントリーポイントを、単一の標準検証サービスに集約してください。」

8. 成功パターンも記録する

失敗を明確に防止した、または表面化させたプラクティスを記録します。

• 決定論的なフィクスチャ
• プロパティテストとファジング
• コントラクトとスキーマの適用
• 終端状態の保証を伴う状態機械モデリング
• 明示的な機能レジストリ
• フォールトインジェクションとカオステスト
• レッド・グリーンの回帰検証

9. 修正時に犯したミスを記録する

実装プロセス自体にミスがなかったか確認します。

• 共通の原因ではなく、症状を修正した
• 重複する抽象化をさらに作成した
• 決して失敗しないテストを書いた
• 統合境界を過剰にモックした
• 古いテスト出力を信頼した、または根拠なく完了を主張した
• 利用側を確認せずに API を変更した
• テストを通すために弱体化した

10. Failure-lessons/README.md を維持する

README ではディレクトリの目的を説明し、次の原則を記録します。

このディレクトリには、何が起きたのか、なぜ起きたのか、どのように修正したのか、修正をどう検証したのか、再発を防ぐためにどの不変条件を設けたのかを含め、再利用可能な失敗クラスごとにエンジニアリング上の失敗を記録します。

次の場合に項目を更新することを明記します。再発したとき、より深い根本原因が判明したとき、アーキテクチャが変更されたとき、検証が強化されたとき、以前の修正が不完全だと判明したとき、または共通の原因を統合するときです。

11. 教訓インデックス（Failure-lessons/lessons-index.md）を維持する

次のコンパクトな表を維持します。

教訓	失敗クラス	防止ルール	システム	ステータス	ドキュメント

12. 「現在適用しているルール」を維持する

lessons-index.md に、プロジェクトで得た最も重要な不変条件をまとめたコンパクトなセクションを追加します（例：不変条件の単一の信頼できる情報源、完了はリソースの準備完了を意味すること、終端状態の保証、呼び出し元のミスを内部サーバーエラーにしないこと）。

13. 教訓を実際のコードに結び付ける

現在のリポジトリにシンボルとパスが存在することを確認します（src/jobs/state_machine.ts、ModelRegistry.resolve(...) など）。実装されていない予定のコンポーネントを捏造しないでください。

14. 教訓をテストに結び付ける

影響の大きい解決済みの失敗は、すべて回帰テストに対応付ける必要があります。 $$\text{失敗} \longrightarrow \text{回帰テスト} \longrightarrow \text{保護される不変条件}$$ 修正に有意義な回帰テストがない場合は、未解決の学習項目として明示します。

15. 回帰テストが実際に機能することを検証する（反証可能性を確認する 3 ステップテスト）

優れた回帰テストは、欠陥が存在するときに失敗する必要があります。

1. 修正済みの実装 $\to$ テストが成功する
2. 欠陥のある／元に戻した実装 $\to$ テストが失敗する
3. 実装を復元 $\to$ テストが成功する

修正を取り除いてもテストが成功する場合、そのテストは、保護を主張している対象を保護していません。

16. 再利用する価値のあるテストパターンを記録する

具体的なテスト手法（決定論的なフィクスチャ、プロパティテスト、コントラクトテスト、フォールトインジェクション）によって明らかになった失敗クラス、その手法を使うべき場面、誤った安心感を与える場面を記録します。

17. 既存の知識の重複を解消する

新しい教訓を追加する前に、Failure-lessons/、docs/、ADR、エージェントのメモリを検索します。すでに教訓がある場合は、更新または統合します。共通の根本原因には相互リンクを設定します。

18. ノイズを残さずに履歴を保存する

要点をまとめたエンジニアリングの知識を保存します。膨大な未加工ログ、一時的な ID、認証情報、秘密情報、アクセストークン、会話の生データは保存しないでください。

19. エージェントの学習システムを更新する

要点をまとめた不変条件をエージェントの学習システムとメモリシステムに同期します。

• agent-kernel remember "<prevention invariant>" --type rule --level critical
• gbrain remember "<failure class>: <invariant>" --provenance "session:<id>" --entity "failure-lessons/<domain>"

20. 結果をコードのようにレビューする

ドキュメントの差分（git diff -- Failure-lessons）を確認します。以下を検証してください。

• 裏付けのない主張や、根本原因の取り違えがないこと。
• 実装名を捏造していないこと、古い参照が残っていないこと。
• すべての項目にステータスラベルと予防ルールがあること。
• 検証の根拠が記録されていること。
• 秘密情報や個人用ローカルパスが誤って含まれていないこと。

21. 個別にコミットする

学習内容のドキュメントを、無関係な実装コミットに紛れ込ませないでください。次のようにすることを推奨します。

docs: capture engineering failure lessons

22. 簡潔な最終レポートを提出する

以下の必須8セクションで構成した最終サマリーを出力します。

1. 使用した学習ツール
2. 作成したファイル
3. 更新したファイル
4. 抽出した主要な教訓
5. 新たに適用するルール
6. 失敗とテストの対応関係
7. 未解決の知識
8. リポジトリの変更

---

判断ルール

• 推測より実証的な根拠を優先する：未検証の仮説を不変条件として記録してはいけません。検証済みの証拠に裏付けられた解決策のみを記録してください。
• 局所的なパッチよりシステム全体の根本原因を優先する：予防ルールを確定する前に、システムアーキテクチャがなぜ欠陥を許したのかを必ず調査してください。
• ルールのアトミック性：agent-kernel と gbrain に適用するルールには、条件を1つ、アクションを1つだけ含めてください。
• サニタイズの不変条件：記録する前に、API キー、トークン、セッション ID、個人用ローカルパス、PII を削除してください。
• フェイルソフトな実行時動作：フックとスクリプトは、ターミナルのワークフローや終了を妨げないよう、オープンに失敗する必要があります。

---

不変条件

• 記録される学習内容はすべて、トランスクリプトまたはアーティファクトの証拠に基づいています。
• 根本原因は、確認済み、強く示唆される、未検証の仮説、不明のいずれかに正直に分類する必要があります。
• 知識は、チケット番号や一時的な参照ではなく、再利用可能な失敗クラスごとに厳密に整理します。
• 影響の大きい失敗に関する教訓はすべて、再現可能な回帰テストに結び付けます（失敗 → 回帰テスト → 保護対象の不変条件）。
• 機密性の高い認証情報、セッショントークン、個人を特定できるPIIをストレージに書き込んではいけません。

---

失敗の分類

未検証の修正

会話には、失敗した、または取り下げられた解決策の試みが含まれています。取り下げられた試みは破棄し、最終的に検証された解決策のみを記録してください。

表面的な診断

システムアーキテクチャがなぜ障害を許したのかを理解せず、1行のパッチだけを記録することです。根底にあるシステム上の条件を把握できるよう、14セクションのスキーマを適用してください。

反証可能性のない回帰テスト

欠陥を再導入しても合格し続ける回帰テストです。カバレッジを認定する前に、反証可能性を3段階で検証する必要があります。

秘密情報の露出リスク

トランスクリプトに、機密性の高い環境変数やキーが含まれています。ストレージコマンドに渡す前に、正規表現によるマスキングでサニタイズしてください。

ルールの陳腐化／不整合

新しいライブラリのバージョンや実行時のリファクタリングによって、以前に学んだルールが無効になっています。古いルールを隔離し、新しい基準を検証してから、Failure-lessons/lessons-index.md で置き換えてください。

---

アンチパターン

• 会話のトランスクリプト全体を、内容を整理せずそのままアーカイブする。
• 失敗を失敗クラスではなく、Jira／GitHub の課題番号で記録する。
• 未検証の仮説を、確認済みの根本原因として記録する。
• バグが再導入されても合格する回帰テストを書く。
• 解決した失敗を、自動回帰テストのカバレッジに結び付けない。
• 異なる複数の失敗クラスを、整理せずに1つのドキュメントにまとめる。
• 価値あるアーキテクチャ上の教訓を含む失敗したアプローチを省いて、履歴をサニタイズする。

完了基準

次のすべてを満たした時点で、fable-learning の実行は完了です。

1. 失敗、発見、修正、テスト結果を含む、セッションの実態を確認している。
2. 根本原因を（確認済み、強く示唆される、未解決の仮説、不明）に正直に分類している。
3. Failure-lessons/ を作成または更新し、README.md、lessons-index.md、testing-and-verification.md、および関連トピックファイルを用意している。
4. すべての項目が14セクションの Failure-Lesson スキーマに準拠し、予防ルールとともに索引に登録されている。
5. 不変条件が、安定したコード参照および回帰テストと結び付いている。
6. 抽出した予防ルールを、利用可能な場合は agent-kernel と gbrain に保存している。
7. 8セクションの最終レポートをユーザーに提出している。

---

段階的なリソース

• Failure lessons ナレッジベースのプロトコル：references/failure-lessons.md
• 深掘り抽出スキーマと分類体系：references/analysis.md
• 複数ターゲットへの保存ルールと統合形式：references/synthesis.md
• 実証的な信頼度とルールの陳腐化：references/confidence-and-drift.md
• 複合ソリューションのアーキテクチャと用語集：references/solution-architecture.md
• トレーニング後のシグナル分類体系：references/post-training-signals.md
• セッションソースアダプター：references/session-sources.md
• スキルパッケージのコンパイル：references/skill-compilation.md
• ウォークスルーの例：examples/learning-walkthrough.md