---

name: understanding-mistakes description: Use when user says something went wrong, AI did Y instead of X, or wants to understand why a deviation happened. Manually invoked post-mortem analysis.

Understanding Mistakes

Overview

Analyze why you deviated from expected behavior. Produce honest self-reflection and document learnings to prevent the same mistake twice.

Process

1. Gather Context

If the issue isn't clear, ask the user:

• "What did you expect to happen?"
• "What actually happened?"

2. Self-Reflect

Analyze your own decision-making honestly:

• What information did I have access to?
• What assumptions did I make?
• Why did I choose this approach over the expected one?
• Did I ignore explicit guidance? Why?

3. Identify the Gap

Determine root cause:

• Missing information in the instruction?
• Ambiguous wording I interpreted differently?
• Over-engineering instinct?
• Default behavior overriding explicit guidance?
• Assumed I knew better?

4. Write Learning Document

Create docs/learnings/YYYY-MM-DD-<topic>.md with this structure:

# Understanding Mistake: <brief title>

**Date:** YYYY-MM-DD
**Context:** <what task/skill was being executed>

## What Was Requested
<The original instruction or expected behavior>

## What Happened Instead
<The actual behavior/deviation>

## Root Cause Analysis
<Why the AI made this choice>
- What information was available
- What assumptions were made
- What reasoning led to the deviation

## Information Gap
<What was missing or unclear>
- Missing context?
- Ambiguous wording?
- Conflicting signals?

## Prevention
<How to avoid this in the future>
- Suggested instruction improvements
- Patterns to watch for

Principles

Principle	Meaning
Honest self-reflection	No excuses, no defensiveness. Genuinely analyze what happened.
Actionable insights	Prevention section must be concrete and usable, not vague.
No blame, just learning	Investigative tone. Goal is improving the system.
Pattern recognition	These docs build a knowledge base. Look for recurring issues.

Common Root Causes

Pattern	Example
Over-engineering	Added filters/complexity not in the spec
Assumed context	Thought I knew what was needed without checking
Ignored explicit guidance	Skill had exact code, I wrote my own
Ambiguous instruction	Multiple valid interpretations, picked wrong one
Default behavior	Fell back to training patterns instead of following instruction

Red Flags in Self-Analysis

If you find yourself thinking:

• "But my way was better" → You ignored explicit guidance
• "I thought it was obvious" → You made assumptions
• "The instruction didn't say NOT to" → You added unrequested complexity
• "I was trying to be helpful" → Over-engineering

These are the insights to document, not excuses to make.