Failure Memory

Record failures. Learn from them. Never repeat them.

Core Concept

Every failure has three parts:

1. 1. What happened (error message, symptom)
2. Why it happened (root cause)
3. How to fix/avoid it (resolution)

This skill stores them in a searchable markdown file and provides a recall mechanism before starting similar tasks.

File Structure

CODEBLOCK0

Recording a Failure

When an error occurs during work, append to memory/failures.md:

CODEBLOCK1

When to Record

Record AUTOMATICALLY when:

• - A shell command exits non-zero and you identify why
• An API call fails and you find the cause
• A config/setup step fails and you resolve it
• You catch yourself repeating a previously-solved mistake
• A sub-agent reports an error with resolution

Do NOT record:

• - Transient network timeouts (unless pattern emerges)
• Intentional test failures
• User-cancelled operations

Pre-Task Recall

Before starting any significant task, search failures for relevant history:

CODEBLOCK2

Or use memory_search if vector search is available:
CODEBLOCK3

If matches found, mention them briefly:

⚠️ Known pitfall: [title] — [prevention tip]

Failure Report

When asked for a failure report or review, generate a summary:

1. 1. Read INLINECODE2
2. Group by category
3. Identify repeat patterns (same root cause appearing multiple times)
4. Suggest systemic fixes for patterns

Report Format

CODEBLOCK4

Initialization

Run scripts/init.sh to set up the failures file:

CODEBLOCK5

Default memory_dir: INLINECODE4

Best Practices

1. 1. Be specific — "EACCES on /var/run/docker.sock" beats "permission error"
2. Include the exact error — Future grep depends on it
3. Tag generously — More tags = better recall
4. Review monthly — Patterns reveal systemic issues
5. Link to fixes — Reference commits, PRs, or config changes when possible