fable-learning

Fable Learning — 失败经验与知识综合引擎

将任何工程对话、Agent 执行轨迹或会话实况转化为持久、可复用的项目知识，并保存到 Failure-lessons/、agent-kernel 规则、gbrain 知识块、复合解决方案文档（docs/solutions/）和可移植的 Playbooks 中。

$$\text{会话实况} \xrightarrow{\text{实况挖掘}} \text{失败、修复、不变量、测试} \xrightarrow{\text{提炼与严谨化}} \text{Failure-lessons/ + agent-kernel + gbrain} \xrightarrow{\text{演进}} \text{Playbooks 与 Skills}$$

---

使命

使命声明：将本次会话转化为持久的项目经验

本次会话包含的工程知识不应随着对话结束而消失。

你的任务是提取已完成工作中可复用的经验，并将其保存为持久的项目知识。

不要生成简单的会话摘要。
不要只罗列发生了哪些变更。
要将失败、发现、纠正、架构决策、调试心得、测试策略和实现错误转化为可复用的工程经验，让未来的贡献者和编码 Agent 能够据此采取行动。

核心目标是：

工程错误只付出一次代价。
此后，项目就应该记住它。

---

适用情形

• 从已完成或进行中的会话中提取经验、已验证的修复或模式。
• 用户调用 /learn、learn、convo-learn、fable-learning，或询问“我们学到了什么？”、“提取经验”、“保存所学内容”或“将会话转化为持久经验”。
• 解决非平凡 Bug、测试回归或配置障碍，并建立可复用的预防性不变量。
• 创建或更新仓库的 Failure-lessons/ 知识库。
• 将用户的纠正、确认或升级反馈记录为后训练信号。
• 将 3 个以上相关的问题—解决方案对综合为 agent-kernel Playbook。
• 通过 fable-skill-creator 将对话要点编译为新的可移植 Skill 包。
• 在会话结束时以无头模式运行（Stop / SessionEnd 钩子事件），记录知识块。

---

不适用情形

• 在不分析对话记录的情况下审查代码差异或拉取请求（fable-review）。
• 根据测试验证应用功能或 Bug 修复是否有效（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+ 规则	终端输出
已解决的非平凡 Bug 或测试框架问题	COMPOUND	docs/solutions/ + CONCEPTS.md	单篇原子化问题—解决方案文档	docs/solutions/YYYY-MM-DD-<slug>.md
“根据这个创建一个技能”或 --compile	COMPILE	skills/<name>/	完整提取 + 通过 fable-skill-creator 编写 SKILL.md	Skill 包
“我们学到了什么？”或 --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

规则：

• 检查实际可用的工具；不要假装执行了不可用的命令。
• 适当时使用可用的等效工具。
• 即使 Agent 记忆工具不可用，仓库文档（Failure-lessons/）仍然是持久可靠的信息来源。

2. 回顾整个相关会话

动笔前，先还原实际发生的情况。检查对话、实现历史、差异、测试、工具输出、评审反馈和当前仓库状态。 不要只关注最终成功的结果。还要从以下内容中提取经验：

• 遇到的错误和不正确的假设
• 失败的方法和调试发现
• 根本原因和架构弱点
• 实现修复和回归问题
• 边缘情况和测试失败
• 评审者的发现和工具限制
• API 契约问题和性能问题
• 数据问题和安全问题
• 运维问题和向后兼容问题
• 被修订的决策，或过早宣称已完成的情况
• 特别有效、值得成为标准实践的方法

不要粉饰历史。 失败的方法往往比最终修复更有价值。

3. 区分事实与假设

对每项重要发现，区分以下类别：

• 已确认的根本原因：由代码、日志跟踪或可复现测试证明。
• 很可能的原因：有强相关证据支持，但具体机制尚未完全确定。
• 待验证的假设：合理的解释，仍需进一步验证。
• 未知：如实记录可观察到的症状，尚未确定原因。

绝不要把推测写成历史事实。

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. 按故障类别组织，而不是按工单编号组织

避免按工单编号或短暂引用来组织文档：

• ❌ 错误 #143、错误 #188、周二发生的问题、PR #92 中修复的问题

优先采用稳定且描述明确的故障类别：

• ✅ 非原子资源发布
• ✅ 在多个入口重复实现验证逻辑
• ✅ 后台作业缺少终态保证
• ✅ 客户端与服务端对 API 语义理解不一致
• ✅ 无法复现原始故障的回归测试

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. 提炼 Bug 背后的经验

不要停留在表面总结（“忘记验证 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. fixed implementation → 测试通过
2. broken/reverted defect → 测试失败
3. restored implementation → 测试通过

如果移除修复后测试仍然通过，那么它就没有保护其声称保护的内容。

16. 记录值得复用的测试模式

记录具体测试技术发现了哪些故障类别、何时应使用这些技术，以及它们何时会带来虚假的信心（如确定性测试夹具、属性测试、契约测试、故障注入）。

17. 去重现有知识

添加新经验前，先搜索 Failure-lessons/、docs/、ADR 和 Agent 记忆。如果该经验已存在，则更新或整合它。为共同根因添加交叉链接。

18. 留存历史，但不保留噪声

保存提炼后的工程知识。不要保留冗长的原始日志、临时 ID、凭据、秘密、访问令牌或原始对话转储。

19. 更新 Agent 学习系统

将提炼后的不变量同步到 Agent 学习和记忆系统：

• 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 的规则必须各自只包含一个条件和一个操作。
• 清理不变量：持久化之前，删除 API 密钥、令牌、会话 ID、私有本地路径和个人身份信息。
• 运行时故障软化：钩子和脚本必须在失败时放行，不得阻止终端工作流或退出操作。

---

不变量

• 每条持久化的学习内容都必须以对话记录或工件证据为依据。
• 根本原因必须如实区分为“已确认”“强烈暗示”“待验证假设”或“未知”。
• 知识必须严格按可复用的失败类别组织，绝不能按工单编号或临时引用组织。
• 所有高影响失败经验都必须关联到可复现的回归测试（failure -> regression test -> invariant being protected）。
• 不得将机密凭据、会话令牌或个人身份信息写入存储。

---

失败分类

未验证的修复

对话中包含失败或已放弃的尝试。丢弃已放弃的尝试；只记录最终经过验证的解决方案。

表面诊断

只记录单行补丁，却没有弄清系统架构为何会允许故障发生。强制采用 14 部分架构，以记录底层的系统性条件。

不可证伪的回归测试

即使缺陷再次引入，回归测试仍然通过。认证测试覆盖前，必须进行 3 步可证伪性验证。

机密泄露风险

对话记录中包含敏感环境变量或密钥。在传递给存储命令之前，使用正则表达式进行脱敏。

规则漂移／过时

先前学到的规则因新库版本或运行时重构而失效。隔离旧规则，验证新的基准，并在 Failure-lessons/lessons-index.md 中用新规则取代旧规则。

---

反模式

• 原封不动地归档完整对话记录，不作提炼。
• 按 Jira／GitHub 问题编号记录失败，而不是按失败类别记录。
• 将未经验证的假设作为已确认的根本原因持久化。
• 编写在 Bug 再次引入时仍会通过的回归测试。
• 未将已解决的故障关联到自动化回归测试覆盖。
• 将多个互不相关的失败类别捆绑到一份杂乱无章的文档中。
• 为了清理历史而省略包含有价值架构经验的失败尝试。

完成标准

满足以下条件时，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 个部分的最终报告。

---

渐进式资源

• 失败教训知识库协议：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