Failure Memory Log

Automatic failure pattern recording and recall system. Prevents repeating the same mistakes by logging errors with context, root cause, and resolution. Use w...

Failure Memory

Record failures. Learn from them. Never repeat them.

Core Concept

Every failure has three parts:

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

memory/
└── failures.md      # All failure records (append-only log)

Recording a Failure

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

## [YYYY-MM-DD HH:mm] <short title>

- **Category:** <build|deploy|config|api|permissions|data|logic|network|dependency>
- **Context:** <what you were trying to do>
- **Error:** `<exact error message or symptom>`
- **Root Cause:** <why it happened>
- **Resolution:** <what fixed it>
- **Prevention:** <how to avoid next time>
- **Tags:** <comma-separated keywords for search>

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:

grep -i "<keyword>" memory/failures.md

Or use memory_search if vector search is available:

memory_search query="<task description> failure error"

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. Read memory/failures.md
2. Group by category
3. Identify repeat patterns (same root cause appearing multiple times)
4. Suggest systemic fixes for patterns

Report Format

# Failure Report — YYYY-MM-DD

## Stats
- Total: N failures recorded
- Top category: <category> (N occurrences)
- Repeat offenders: N patterns seen 2+ times

## Repeat Patterns
### <pattern name>
- Seen: N times
- Root cause: <shared cause>
- Systemic fix: <recommendation>

## Recent Failures (last 7 days)
- [date] <title> — <resolution>

Initialization

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

bash scripts/init.sh [memory_dir]

Default memory_dir: ./memory

Best Practices

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