fable-learning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fable Learning — Failure Lessons & Knowledge Synthesis Engine

Fable Learning — 失败教训与知识综合引擎

Turn any engineering conversation, agent trajectory, or session realities into durable, reusable project knowledge saved in Failure-lessons/
, agent-kernel
rules, gbrain
chunks, compound solution docs (

docs/solutions/

), and portable Playbooks.

$$\text{Session Realities} \xrightarrow{\text{Reality Mining}} \text{Failures, Fixes, Invariants, Tests} \xrightarrow{\text{Distillation & Rigor}} \text{Failure-lessons/ + agent-kernel + gbrain} \xrightarrow{\text{Evolution}} \text{Playbooks & Skills}$$

将任何工程对话、Agent 轨迹或会话现状转化为持久、可复用的项目知识，并保存到 Failure-lessons/
、agent-kernel
规则、gbrain
chunks、复合解决方案文档 (

docs/solutions/

) 和可移植的 Playbooks 中。

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

Mission

Mission Statement: Convert This Session Into Durable Project Learnings

任务声明：将本次会话转化为持久项目学习成果

This session contains engineering knowledge that should not disappear when the conversation ends.

Your task is to extract the reusable lessons from the work completed and persist them as durable project knowledge.

Do not produce a simple session summary.
Do not merely list what changed.
Convert failures, discoveries, corrections, architectural decisions, debugging insights, testing strategies, and implementation mistakes into reusable engineering lessons that future contributors and coding agents can act on.

The core objective is:

Pay for an engineering mistake once.
After that, the project should remember it.

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

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

不要生成简单的会话摘要。
不要仅仅罗列发生了哪些变更。
将失败、发现、纠正、架构决策、调试洞察、测试策略和实施错误转化为未来的贡献者和编码 Agent 可据此行动的可复用工程教训。

核心目标是：

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

Activate When

何时启用

Extracting takeaways, verified fixes, or patterns from a completed or in-progress session.
User invokes
```
/learn
```
,
```
learn
```
,
```
convo-learn
```
,
```
fable-learning
```
, "what did we learn?", "extract learnings", "save what we learned", or "convert session into durable learnings".
Resolving a non-trivial bug, test regression, or configuration obstacle and establishing a reusable prevention invariant.
Creating or updating the repository's
```
Failure-lessons/
```
knowledge base.
Capturing user corrections, confirmations, or escalations as post-training signals.
Synthesizing 3+ related problem-solution pairs into an
```
agent-kernel
```
Playbook.
Compiling conversation takeaways into a new portable Skill package via
```
fable-skill-creator
```
.
Running headless at session completion (
```
Stop
```
/
```
SessionEnd
```
hook events) to record learning chunks.

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

Do Not Activate When

何时不要启用

Reviewing code diffs or pull requests without transcript analysis (
```
fable-review
```
).
Verifying whether an application feature or bugfix works against tests (
```
fable-verify
```
).
Storing user preferences or static environment facts into memory (
```
fable-memory
```
).
Running quantitative benchmarks or comparing prompt models (
```
fable-eval
```
).

审查代码 diff 或 pull request，但未分析会话记录（使用
```
fable-review
```
）。
根据测试验证应用功能或 bugfix 是否有效（使用
```
fable-verify
```
）。
将用户偏好或静态环境信息存入记忆（使用
```
fable-memory
```
）。
运行定量基准测试或比较 prompt 模型（使用
```
fable-eval
```
）。

Situation Classification

场景分类

Invocation Pattern	Mode	Primary Target Storage	Action & Depth	Output Artifact
User asks for failure lessons, postmortem, or root cause codification	`FAILURE_LESSONS`	`Failure-lessons/` + `agent-kernel` + `gbrain`	Full 22-step failure extraction & regression linking	`Failure-lessons/*.md` + Report
Explicit session ID or transcript file	`ANALYZE`	`Failure-lessons/` + `agent-kernel` + `gbrain`	Full 4-category extraction & synthesis	Structured markdown report
Short session or `--depth lightweight`	`QUICK`	`agent-kernel` + `gbrain`	Top 5 atomic $L3+$ rules	Terminal output
Resolved non-trivial bug or harness issue	`COMPOUND`	`docs/solutions/` + `CONCEPTS.md`	Single atomic problem-solution doc	`docs/solutions/YYYY-MM-DD-<slug>.md`
"make a skill from this" or `--compile`	`COMPILE`	`skills/<name>/`	Full extraction + author `SKILL.md` via `fable-skill-creator`	Skill package
"what did we learn?" or `--recall`	`RECALL`	Terminal output / summary	Query `gbrain` and `agent-kernel` to synthesize	Interactive digest
Post-session hook ( `Stop` / `SessionEnd` )	`HEADLESS`	`agent-kernel` + `gbrain`	Automated background extraction with fail-soft safety	`Documentation complete` / `skipped`

调用模式	模式	主要目标存储位置	操作与深度	输出产物
用户要求记录失败教训、postmortem 或根因编码	`FAILURE_LESSONS`	`Failure-lessons/` + `agent-kernel` + `gbrain`	完整的 22 步失败提取与回归关联	`Failure-lessons/*.md` + 报告
明确指定 session ID 或 transcript 文件	`ANALYZE`	`Failure-lessons/` + `agent-kernel` + `gbrain`	完整的 4 类提取与综合	结构化 Markdown 报告
短会话或 `--depth lightweight`	`QUICK`	`agent-kernel` + `gbrain`	5 条原子化 L3+ 规则	终端输出
已解决的非简单 bug 或 test harness 问题	`COMPOUND`	`docs/solutions/` + `CONCEPTS.md`	单个原子化问题—解决方案文档	`docs/solutions/YYYY-MM-DD-<slug>.md`
“据此制作一个 skill”或 `--compile`	`COMPILE`	`skills/<name>/`	完整提取，并通过 `fable-skill-creator` 编写 `SKILL.md`	Skill 包
“我们学到了什么？”或 `--recall`	`RECALL`	终端输出／摘要	查询 `gbrain` 和 `agent-kernel` 并进行综合	交互式摘要
会话后 hook（ `Stop` / `SessionEnd` ）	`HEADLESS`	`agent-kernel` + `gbrain`	使用 fail-soft 安全机制执行自动化后台提取	`Documentation complete` / `skipped`

Protocol

The 22-Step Failure-Lessons Extraction Protocol

22 步失败教训提取协议

1. Use the Learning Tools Available to You

1. 使用你可用的学习工具

Inspect what tools are actually available in the host environment:

```
/learn
```
,
```
learn
```
```
gsd:extract-learnings
```
```
/convo-learn
```
,
```
/fable-learning
```
```
agent-kernel remember
```
```
gbrain remember
```

Rules:

Inspect what is actually available; do not pretend an unavailable command was executed.
Use equivalent available tooling when appropriate.
The repository documentation (
```
Failure-lessons/
```
) remains the durable source of truth even when agent-memory tools are unavailable.

检查宿主环境中实际可用的工具：

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

规则：

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

2. Review the Entire Relevant Session

2. 审阅整个相关会话

Before writing anything, reconstruct what actually happened. Review the conversation, implementation history, diffs, tests, tool output, review feedback, and current repository state. Look for more than the final successful result. Extract knowledge from:

bugs encountered and incorrect assumptions
failed approaches and debugging discoveries
root causes and architectural weaknesses
implementation fixes and regressions
edge cases and test failures
reviewer findings and tooling limitations
API-contract problems and performance issues
data problems and security issues
operational issues and backwards-compatibility problems
decisions that were revised or places where completion was claimed too early
things that worked particularly well and should become standard practice

Do not sanitize the history. A failed approach often contains a more valuable lesson than the final fix.

在写入任何内容之前，重构实际发生的事情。审阅对话、实现历史、diff、测试、工具输出、评审反馈和当前仓库状态。

不要只关注最终成功的结果。尝试从以下内容中提取知识：

遇到的 bug 和错误假设
失败的方法和调试发现
根因和架构缺陷
实现修复和回归问题
边界情况与测试失败
评审发现和工具限制
API 契约问题和性能问题
数据问题与安全问题
运维问题和向后兼容问题
被修订的决策，或过早宣称完成的地方
特别有效且应成为标准实践的做法

不要清洗历史。失败的尝试通常比最终修复包含更宝贵的教训。

3. Separate Facts From Hypotheses

3. 区分事实与假设

For every important finding distinguish between:

```
Confirmed root cause
```
: Proven by code, log traces, or reproducible tests.
```
Strongly indicated cause
```
: Highly probable, supported by strong correlation, but mechanism not 100% isolated.
```
Open hypothesis
```
: Plausible explanation requiring further validation.
```
Unknown
```
: Observable symptom documented honestly, cause not yet determined.

Never convert speculation into historical fact.

对于每项重要发现，区分：

```
已确认根因
```
：由代码、日志跟踪或可复现测试证明。
```
强烈指示的原因
```
：概率很高，并有强相关性支持，但机制尚未 100% 隔离。
```
开放假设
```
：合理解释，但仍需进一步验证。
```
未知
```
：如实记录可观察到的症状，但原因尚未确定。

永远不要把推测转化为历史事实。

4. Create or Update the Project Failure-Lessons Knowledge Base

4. 创建或更新项目失败教训知识库

Use the directory:

text

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/

does not exist, create it. If the repository already has an equivalent established location, preserve the existing convention unless explicitly instructed otherwise. Do not create a competing knowledge system unnecessarily.

Topic document examples:

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

. Do not create empty files simply to match a template.

使用以下目录：

text

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. Organize by Failure Class, Not Ticket Number

5. 按失败类别组织，而不是按工单编号组织

Avoid documentation organized by ticket numbers or ephemeral references:

❌

Bug #143

Bug #188

Issue from Tuesday

Problem we fixed in PR #92

Prefer stable, descriptive failure classes:

✅
```
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

避免按工单编号或临时引用组织文档：

❌

Bug #143

、

Bug #188

、

Issue from Tuesday

、

Problem we fixed in PR #92

优先使用稳定且具有描述性的失败类别：

✅ 非原子资源发布
✅ 跨入口点重复实现验证逻辑
✅ 缺少终态保证的后台任务
✅ 客户端与服务端对 API 语义理解不一致
✅ 从未复现原始故障的回归测试

6. Use the Canonical Failure-Lesson Schema

6. 使用标准失败教训 Schema

Every meaningful lesson follows this 14-section schema:

markdown

undefined

每条有意义的教训都应遵循以下 14 节 schema：

markdown

undefined

[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.

undefined

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

undefined

7. Extract the Lesson Behind the Bug

7. 提取 Bug 背后的教训

Do not stop at superficial summaries ("We forgot to validate X"). Ask:

Why could validation be forgotten?
Was the same invariant implemented independently across entry points?
Was the contract unclear or failure mode hidden?
Was the test too narrow or state duplicated?

Transform:

"Endpoint B forgot the tenant validation." Into: "Domain invariants implemented independently across entry points will drift. Route all entry points through one canonical validation service."

不要停留在表面总结（“我们忘记验证 X”）。追问：

为什么会忘记验证？
同一个不变量是否在多个入口点被独立实现？
契约是否不明确，或故障模式是否被隐藏？
测试是否过于狭窄，或状态是否重复？

将：

“端点 B 忘记执行租户验证。”

转化为：

“跨入口点独立实现的领域不变量会发生漂移。应让所有入口点统一通过一个规范化验证服务。”

8. Capture Successful Patterns Too

8. 同时记录成功模式

Record practices that clearly prevented or exposed failures:

Deterministic fixtures
Property tests and fuzzing
Contract and schema enforcement
State-machine modeling with terminal-state guarantees
Explicit capability registries
Fault injection and chaos testing
Red-green regression verification

记录那些明确预防或暴露了故障的实践：

确定性 fixtures
property tests 与 fuzzing
contract 与 schema 强制检查
带终态保证的状态机建模
显式 capability registries
故障注入与 chaos testing
红—绿回归验证

9. Capture Mistakes Made During the Fix

9. 记录修复过程中犯下的错误

Review whether the implementation process itself contained mistakes:

Fixing the symptom instead of the shared cause
Creating another duplicate abstraction
Writing a test that could never fail
Over-mocking an integration boundary
Trusting stale test output or claiming completion without evidence
Changing an API without checking consumers
Weakening tests to make them pass

检查实施过程本身是否包含错误：

只修复症状，而未修复共同根因
创建另一个重复抽象
编写永远不可能失败的测试
过度 mock 集成边界
信任过期的测试输出，或在没有证据的情况下宣称完成
未检查消费者就更改 API
削弱测试以使其通过

10. Maintain

Failure-lessons/README.md

10. 维护

Failure-lessons/README.md

The README explains the purpose of the directory and captures this principle:

This directory records engineering failures by reusable failure class, including what happened, why it happened, how it was fixed, how the fix was verified, and which invariant now prevents recurrence.

State when entries should be updated: recurrence, deeper root cause discovered, architecture changes, stronger verification added, previous fix proven incomplete, or consolidation of shared causes.

README 应说明该目录的用途，并体现以下原则：

本目录按可复用的失败类别记录工程失败，包括发生了什么、为何发生、如何修复、如何验证修复，以及现在使用哪项不变量防止问题再次发生。

说明条目应何时更新：问题再次发生、发现更深层根因、架构变化、加入更强验证、先前修复被证明不完整，或合并共同根因。

11. Maintain a Lessons Index (

Failure-lessons/lessons-index.md

)

11. 维护教训索引（

Failure-lessons/lessons-index.md

）

Maintain a compact table:

Lesson	Failure Class	Prevention Rule	System	Status	Document

维护以下紧凑表格：

教训	失败类别	预防规则	系统	状态	文档

12. Maintain "Rules We Now Enforce"

12. 维护“现在执行的规则”

Add a compact section in

lessons-index.md

containing the strongest invariants learned from the project (e.g. single source of invariant truth, completion implies resource readiness, terminal-state guarantees, caller mistakes must not be internal server faults).

在

lessons-index.md

中维护一个紧凑章节，记录项目中最重要的不变量，例如：单一不变量事实来源、完成即代表资源可用、终态保证，以及调用方错误不得转化为内部服务故障。

13. Connect Lessons to Real Code

13. 将教训关联到真实代码

Confirm symbols and paths exist in the current repository. Use stable references (

src/jobs/state_machine.ts

ModelRegistry.resolve(...)

). Do not invent planned components that were never implemented.

确认符号和路径存在于当前仓库中。使用稳定引用（

src/jobs/state_machine.ts

、

ModelRegistry.resolve(...)

）。不要虚构从未实现的计划组件。

14. Connect Lessons to Tests

14. 将教训关联到测试

Every resolved high-impact failure must map to regression coverage: $$\text{Failure} \longrightarrow \text{Regression Test} \longrightarrow \text{Protected Invariant}$$ If a fix has no meaningful regression test, flag it as an unresolved learning item.

每个已解决的高影响故障都必须映射到回归覆盖： $$\text{失败} \longrightarrow \text{回归测试} \longrightarrow \text{所保护的不变量}$$ 如果某项修复没有有意义的回归测试，应将其标记为未解决的学习事项。

15. Verify Regression Tests Are Real (The 3-Step Falsifiability Test)

15. 验证回归测试的真实性（3 步可证伪性测试）

A strong regression test must fail when the defect is present:

```
fixed implementation
```
$\to$ test passes
```
broken/reverted defect
```
$\to$ test fails
```
restored implementation
```
$\to$ test passes

If a test still passes after the fix is removed, it does not protect what it claims to protect.

强回归测试必须在缺陷存在时失败：

```
修复后的实现
```
$\to$ 测试通过
```
重新引入缺陷的实现
```
$\to$ 测试失败
```
恢复修复后的实现
```
$\to$ 测试通过

如果移除修复后测试仍然通过，则它无法保护其声称保护的内容。

16. Capture Testing Patterns Worth Reusing

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

Document what failure classes were exposed by specific testing techniques (deterministic fixtures, property tests, contract tests, fault injection), when to use them, and when they offer false confidence.

记录特定测试技术暴露了哪些失败类别（确定性 fixtures、property tests、contract tests、故障注入），何时使用这些技术，以及它们何时会造成虚假信心。

17. Deduplicate Existing Knowledge

17. 去除已有知识中的重复内容

Failure-lessons/

docs/

, ADRs, and agent memory before adding new lessons. If the lesson already exists, update or consolidate it. Cross-link shared root causes.

添加新教训前，先搜索

Failure-lessons/

、

docs/

、ADR 和 Agent 记忆。如果对应教训已经存在，应更新或合并它，并交叉链接共同根因。

18. Preserve History Without Preserving Noise

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

Store distilled engineering knowledge. Do not preserve giant raw logs, temporary IDs, credentials, secrets, access tokens, or raw conversation dumps.

存储经过提炼的工程知识。不要保留庞大的原始日志、临时 ID、凭据、密钥、访问令牌或原始对话转储。

19. Update Agent Learning Systems

19. 更新 Agent 学习系统

Synchronize distilled invariants into agent learning and memory systems:

agent-kernel remember "<prevention invariant>" --type rule --level critical

gbrain remember "<failure class>: <invariant>" --provenance "session:<id>" --entity "failure-lessons/<domain>"

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

agent-kernel remember "<prevention invariant>" --type rule --level critical

gbrain remember "<failure class>: <invariant>" --provenance "session:<id>" --entity "failure-lessons/<domain>"

20. Review the Result Like Code

20. 像审查代码一样审查结果

Inspect the documentation diff (

git diff -- Failure-lessons

). Verify:

No unsupported claims or inverted root causes.
No invented implementation names or stale references.
All entries have status labels and prevention rules.
Verification evidence is documented.
No accidental secrets or private local paths.

检查文档 diff（

git diff -- Failure-lessons

）。验证：

不存在无依据的主张或颠倒的根因。
不存在虚构的实现名称或过期引用。
所有条目都有状态标签和预防规则。
已记录验证证据。
不存在意外泄露的密钥或私有本地路径。

21. Commit Separately

21. 单独提交

Do not hide learning documentation inside an unrelated implementation commit. Prefer:

text

docs: capture engineering failure lessons

不要将学习文档隐藏在无关的实现提交中。推荐使用：

text

docs: capture engineering failure lessons

22. Deliver Concise Final Report

22. 交付简洁的最终报告

Emit a final summary structured with the 8 required sections:

Learning tools used
Files created
Files updated
Core lessons extracted
Rules we now enforce
Failure-to-test mappings
Unresolved knowledge
Repository changes

输出包含以下 8 个必需章节的最终摘要：

使用的学习工具
创建的文件
更新的文件
提取出的核心教训
现在执行的规则
故障到测试的映射
未解决的知识
仓库变更

Decision Rules

决策规则

Empirical Grounding Over Speculation: Never persist an unverified hypothesis as an invariant. Only persist solutions backed by verified evidence.
Systemic Root Causes Over Local Patches: Always investigate why the system architecture allowed the defect before finalizing the prevention rule.
Atomicity in Rules: Rules pushed to
```
agent-kernel
```
and
```
gbrain
```
must contain one condition and one action.
Sanitization Invariant: Strip API keys, tokens, session IDs, private local paths, and PII before persistence.
Fail-Soft Runtime: Hooks and scripts must fail open without blocking terminal workflows or exits.

以经验依据为准，而非臆测：永远不要将未经验证的假设作为不变量持久化。只持久化有已验证证据支持的解决方案。
关注系统性根因，而非局部补丁：在最终确定预防规则前，始终调查系统架构为何允许该缺陷发生。
规则原子性：推送到
```
agent-kernel
```
和
```
gbrain
```
的规则必须只包含一个条件和一个动作。
脱敏不变量：持久化前，移除 API key、token、session ID、私有本地路径和 PII。
Fail-Soft Runtime：Hook 和脚本必须采用 fail-open 机制，不得阻塞终端工作流或退出流程。

Invariants

不变量

Every persisted learning chunk is grounded in transcript or artifact evidence.
Root causes must be honestly separated into Confirmed, Strongly indicated, Open hypothesis, or Unknown.
Knowledge is organized strictly by reusable failure class, never ticket numbers or ephemeral references.
All high-impact failure lessons connect to reproducible regression tests (
```
failure -> regression test -> invariant being protected
```
).
No confidential credentials, session tokens, or private PII are written to storage.

每个持久化的学习内容都必须以会话记录或产物证据为依据。

根因必须诚实地分为

Confirmed

、

Strongly indicated

、

Open hypothesis

或

Unknown

。

知识严格按可复用的失败类别组织，绝不按工单编号或临时引用组织。
所有高影响失败教训都必须关联到可复现的回归测试（
```
failure -> regression test -> invariant being protected
```
）。
不得将机密凭据、session token 或私有 PII 写入存储。

Failure Taxonomy

失败分类体系

Unverified Fixes

未验证的修复

The conversation contains attempted solutions that failed or were abandoned. Discard abandoned attempts; record only the final verified resolution.

会话包含失败或被放弃的尝试性解决方案。丢弃被放弃的尝试；仅记录最终经过验证的解决方案。

Superficial Diagnoses

表面诊断

Documenting a one-line patch without understanding why the system architecture permitted the failure. Enforce the 14-section schema to capture the underlying systemic condition.

仅记录一行补丁，却未理解系统架构为何允许故障发生。强制使用 14 节 schema 捕获底层系统性条件。

Non-Falsifiable Regression Tests

不可证伪的回归测试

Regression tests that continue to pass even when the defect is reintroduced. Require 3-step falsifiability verification before certifying coverage.

重新引入缺陷后仍然通过的回归测试。在认证覆盖前，必须完成 3 步可证伪性验证。

Secret Exposure Risk

密钥暴露风险

Transcript contains sensitive environment variables or keys. Sanitize through regex redaction before passing to storage commands.

会话包含敏感的环境变量或 key。通过 regex 脱敏后，再将内容传递给存储命令。

Rule Drift / Obsolescence

规则漂移／过时

A previously learned rule is invalidated by a new library version or runtime refactor. Quarantine the old rule, verify the new baseline, and supersede it in

Failure-lessons/lessons-index.md

新库版本或运行时重构使先前学习的规则失效。隔离旧规则，验证新基线，并在

Failure-lessons/lessons-index.md

中将其标记为已被替代。

Anti-Patterns

反模式

Archiving entire conversation transcripts verbatim without distillation.
Documenting failures by Jira/GitHub issue numbers rather than failure classes.
Persisting unverified hypotheses as confirmed root causes.
Writing regression tests that pass even when the bug is reintroduced.
Failing to link a resolved failure to automated regression test coverage.
Bundling multiple disparate failure classes into one unorganized document.
Sanitizing history by omitting failed approaches that contain valuable architectural lessons.

未经过提炼，逐字归档整个对话记录。
按 Jira/GitHub issue 编号记录失败，而不是按失败类别记录。
将未经验证的假设作为已确认根因持久化。
编写重新引入 bug 后仍然通过的回归测试。
未将已解决的失败关联到自动化回归测试覆盖。
将多个无关联的失败类别捆绑到一个无组织的文档中。
通过省略失败尝试来清洗历史，而这些尝试往往包含宝贵的架构教训。

Completion Criteria

完成标准

Execution of

fable-learning

completes when:

Session realities have been reviewed across failures, discoveries, corrections, and test results.
Root causes are honestly classified (Confirmed, Strongly indicated, Open hypothesis, Unknown).

Failure-lessons/

is created or updated with

README.md

lessons-index.md

testing-and-verification.md

, and relevant topic files.

All entries adhere to the 14-section Failure-Lesson schema and are indexed with prevention rules.
Invariants are connected to stable code references and regression tests.
Distilled prevention rules are persisted to
```
agent-kernel
```
and
```
gbrain
```
if available.
The 8-section final report is delivered to the user.

执行

fable-learning

后应满足以下条件：

已跨失败、发现、纠正和测试结果审阅会话现状。

根因已被诚实分类（

Confirmed

、

Strongly indicated

、

Open hypothesis

、

Unknown

）。

已创建或更新

Failure-lessons/

，并包含

README.md

、

lessons-index.md

、

testing-and-verification.md

和相关主题文件。

所有条目均遵循 14 节 Failure-Lesson schema，并已使用预防规则建立索引。
不变量已关联到稳定的代码引用和回归测试。
如果相关工具可用，提炼后的预防规则已持久化到
```
agent-kernel
```
和
```
gbrain
```
。
已向用户交付包含 8 个章节的最终报告。

Progressive Resources

渐进式资源

Failure lessons knowledge base protocol:
```
references/failure-lessons.md
```
Deep extraction schema & taxonomy:
```
references/analysis.md
```
Multi-target storage rules & synthesis formats:
```
references/synthesis.md
```
Empirical confidence & rule drift:
```
references/confidence-and-drift.md
```
Compound solution architecture & vocabulary:
```
references/solution-architecture.md
```
Post-training signal taxonomy:
```
references/post-training-signals.md
```
Session source adapters:
```
references/session-sources.md
```
Skill package compilation:
```
references/skill-compilation.md
```
Walkthrough example:
```
examples/learning-walkthrough.md
```

失败教训知识库协议：
```
references/failure-lessons.md
```
深度提取 schema 与分类体系：
```
references/analysis.md
```
多目标存储规则与综合格式：
```
references/synthesis.md
```
经验置信度与规则漂移：
```
references/confidence-and-drift.md
```
复合解决方案架构与词汇：
```
references/solution-architecture.md
```
训练后信号分类：
```
references/post-training-signals.md
```
Session 来源适配器：
```
references/session-sources.md
```
Skill 包编译：
```
references/skill-compilation.md
```
演练示例：
```
examples/learning-walkthrough.md
```

fable-learning

Original

Translation

Fable Learning — Failure Lessons & Knowledge Synthesis Engine

Fable Learning — 失败教训与知识综合引擎

Mission

Mission

Mission Statement: Convert This Session Into Durable Project Learnings

任务声明：将本次会话转化为持久项目学习成果

Activate When

何时启用

Do Not Activate When

何时不要启用

Situation Classification

场景分类

Protocol

Protocol

The 22-Step Failure-Lessons Extraction Protocol

22 步失败教训提取协议

1. Use the Learning Tools Available to You

1. 使用你可用的学习工具

2. Review the Entire Relevant Session

2. 审阅整个相关会话

3. Separate Facts From Hypotheses

3. 区分事实与假设

4. Create or Update the Project Failure-Lessons Knowledge Base

4. 创建或更新项目失败教训知识库

5. Organize by Failure Class, Not Ticket Number

5. 按失败类别组织，而不是按工单编号组织

6. Use the Canonical Failure-Lesson Schema

6. 使用标准失败教训 Schema

[Failure / lesson name]

[Failure / lesson name]

Context

Context

What happened

What happened

Observable symptom

Observable symptom

Impact

Impact

Incorrect assumption

Incorrect assumption

Root cause

Root cause

Why the architecture allowed it

Why the architecture allowed it

Fix

Fix

Verification

Verification

Prevention rule

Prevention rule

Reusable lesson

Reusable lesson

Related code

Related code

Related tests

Related tests

Related lessons

Related lessons

Status

Status

7. Extract the Lesson Behind the Bug

7. 提取 Bug 背后的教训

8. Capture Successful Patterns Too

8. 同时记录成功模式

9. Capture Mistakes Made During the Fix

9. 记录修复过程中犯下的错误

10. Maintain Failure-lessons/README.md

10. 维护 Failure-lessons/README.md

11. Maintain a Lessons Index (Failure-lessons/lessons-index.md)

11. 维护教训索引（Failure-lessons/lessons-index.md）

12. Maintain "Rules We Now Enforce"

12. 维护“现在执行的规则”

13. Connect Lessons to Real Code

13. 将教训关联到真实代码

14. Connect Lessons to Tests

14. 将教训关联到测试

15. Verify Regression Tests Are Real (The 3-Step Falsifiability Test)

10. Maintain
`Failure-lessons/README.md`

10. 维护
`Failure-lessons/README.md`

11. Maintain a Lessons Index (
`Failure-lessons/lessons-index.md`
)

11. 维护教训索引（
`Failure-lessons/lessons-index.md`
）