Post-Mortems & Playbooks

Two complementary systems for learning from experience: post-mortems document what went wrong, playbooks document what went right. Together they form the agent's institutional knowledge.

Post-Mortems

For significant failures (>30 min wasted, money lost, or the operator had to catch the mistake), the agent writes a structured post-mortem in memory/postmortems/.

Template

# API Integration — Timezone Bug

## What happened
Scheduled action triggered at wrong time — calendar comparison used UTC vs local time

## Root cause
ICS timestamps weren't normalized before comparison. Day-boundary math was silently wrong.

## Fix
Added timezone normalization before all calendar comparisons

## Prevention
Added to SOUL.md: "Normalize timezones before comparing any time-based data"

What triggers a post-mortem

The threshold is deliberate — not every mistake needs one:

• Time cost: >30 minutes wasted debugging or recovering
• Financial cost: Money lost or wasted (even small amounts)
• Operator intervention: The human had to catch something the agent should have caught
• Cascading failure: One error caused downstream problems

Routine mistakes (typos, wrong model selection, minor formatting issues) belong in the daily note's Mistakes/Lessons section, not in a post-mortem.

Searchability

Post-mortems are searchable via memory_search, so future sessions can find prior debugging work before starting from scratch. This has saved hours on recurring issues — a timezone bug today surfaces the timezone post-mortem from last week, complete with root cause and fix.

Playbooks

When a "What Worked & Why" pattern from daily notes has been validated across 2+ instances, it gets promoted to memory/playbook/. Playbooks are the positive counterpart to post-mortems — they document what to do, not just what to avoid.

The agent checks playbooks before attempting unfamiliar operations. This creates a growing library of proven approaches that compound over time.

Examples of playbook-worthy patterns:

• How to structure a governance forum comment that gets engagement
• The sequence for safely testing a new DeFi protocol
• How to diagnose and recover from a gateway session timeout

Anti-Patterns

Rule explosion

Every edge case gets a standing order → AGENTS.md becomes 50 pages → agent can't follow all rules → more violations → more rules. Fix: Human review gate filters aggressively. Most failures need a daily note, not a rule.

Self-referential loops

Agent decides to improve the improvement system → builds scripts to manage scripts → meta-optimization replaces actual work. Fix: Self-improvement is scoped to the learning pipeline. No autonomous modification of the pipeline itself.

Verbal-only acknowledgments

"I'll remember that" or "good point" without a file write = no learning happened. The agent doesn't persist between sessions. Its memory IS the files. Fix: Standing order with trigger phrases. No exceptions.

Stale rules that no longer apply

Rules added for a specific context stick around after the context changes → agent follows outdated constraints. Fix: Periodic rule review during memory maintenance. Rules should have "added because" context so reviewers can tell if they're still relevant.