fable-learning

Fable Learning — Failure Lessons & Knowledge Synthesis Engine

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}$$

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.

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 through an approved authoring workflow.
Running headless at session completion (Stop / SessionEnd hook events) to record learning chunks.

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 (use an independent evaluation protocol).

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 + approved authoring review for `SKILL.md`	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`

Protocol

The 22-Step Failure-Lessons Extraction Protocol

1. Use the Learning Tools Available to You

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.

2. Review the Entire Relevant Session

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.

3. Separate Facts From Hypotheses

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.

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

Use the directory:

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)

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

5. Organize by Failure Class, Not Ticket Number

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

6. Use the Canonical Failure-Lesson Schema

Every meaningful lesson follows this 14-section schema:

## [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. Extract the Lesson Behind the 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."

8. Capture Successful Patterns Too

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

9. Capture Mistakes Made During the Fix

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

10. Maintain `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.

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

Maintain a compact table:

Lesson	Failure Class	Prevention Rule	System	Status	Document

12. Maintain "Rules We Now Enforce"

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

13. Connect Lessons to Real Code

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.

14. Connect Lessons to Tests

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.

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

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.

16. Capture Testing Patterns Worth Reusing

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.

17. Deduplicate Existing Knowledge

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

18. Preserve History Without Preserving Noise

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

19. Update Agent Learning Systems

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>"

20. Review the Result Like Code

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.

21. Commit Separately

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

docs: capture engineering failure lessons

22. Deliver Concise Final Report

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

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.

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.

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.

Non-Falsifiable Regression Tests

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

Secret Exposure Risk

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

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.

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.

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.

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