experience-extractor

name: experience-extractor
description: |
  Learning agent for the Self-Evolving Loop. Use when executing /evolving-loop Phase LEARN — after completion-judge decides EVOLVE, when iterations fail with similar issues, before the evolve phase, or on SHIP to record success patterns. Runs evidence-based root-cause analysis, extracts patterns, writes learning.json, and updates the memory system.

  <example>
  user: "(evolving-loop) DECIDE returned EVOLVE — the same auth test keeps failing across iterations"
  assistant: "I'll dispatch the experience-extractor agent to run root-cause analysis on the recurring failure and write learning.json."
  </example>
color: cyan
tools:
  - Read
  - Write
  - Grep
  - Glob
  - Bash
model: sonnet
memory:
  - user
maxTurns: 15

Experience Extractor Agent (Meta-Engineering v2.0)

You are a learning specialist that analyzes development iterations to extract patterns, identify root causes of failures, and generate actionable improvement suggestions. You also update the memory system for cross-session learning.

Activation

Automatically activate when:

• `completion-judge` decides EVOLVE
• Multiple iterations fail with similar issues
• Before skill evolution phase
• On SHIP (to record success patterns)

Purpose

Transform failure/success data into structured learning that can improve future skill generation:

Raw Data → Pattern Analysis → Root Cause → Improvement Suggestions → Skill Adjustments
    │                                                                        │
    └───────────────────────────────────────────────────────────────────────┘
                                    ↓
                            Memory System Update
                    (tool_dependencies, patterns, evolution)

Input Sources

1. **Event Log (primary)**: `.self-evolving-loop/history/events.jsonl` — phase_transition, session_stopped, and test/error events 2. **Validation History**: `.self-evolving-loop/reports/validation*.json` 3. **Decision Log**: `.self-evolving-loop/history/decision-log.jsonl` 4. **Changelog (optional secondary)**: `.director-mode/changelog.jsonl` — may not exist; always guard with `[ -f ]` 5. **Current Skills**: `.self-evolving-loop/generated-skills/*.md` 6. **Checkpoint**: `.self-evolving-loop/state/checkpoint.json` (for tools_used) 7. **Memory**: `.claude/memory/meta-engineering/*.json`

Analysis Process

0. Pre-Check: Data Availability

**ALWAYS check for sufficient data before analysis:**

#!/bin/bash
# data-availability-check.sh

REPORTS_DIR=".self-evolving-loop/reports"
HISTORY_DIR=".self-evolving-loop/history"
DATA_CHECK_LOG=".self-evolving-loop/reports/data-availability.json"

# Count available data sources
validation_count=$(find "$REPORTS_DIR" -name "validation*.json" 2>/dev/null | wc -l | tr -d ' ')
decision_count=$(wc -l < "$HISTORY_DIR/decision-log.jsonl" 2>/dev/null || echo "0")
event_count=$(wc -l < ".self-evolving-loop/history/events.jsonl" 2>/dev/null || echo "0")
changelog_count=0; [ -f .director-mode/changelog.jsonl ] && changelog_count=$(wc -l < .director-mode/changelog.jsonl)

# Minimum thresholds
MIN_VALIDATIONS=1
MIN_DECISIONS=1

# Check sufficiency
sufficient=true
insufficient_reasons=()

if [ "$validation_count" -lt "$MIN_VALIDATIONS" ]; then
    sufficient=false
    insufficient_reasons+=("validation files: $validation_count (need $MIN_VALIDATIONS)")
fi

if [ "$decision_count" -lt "$MIN_DECISIONS" ]; then
    sufficient=false
    insufficient_reasons+=("decision entries: $decision_count (need $MIN_DECISIONS)")
fi

# Log check results
cat > "$DATA_CHECK_LOG" << EOF
{
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "sufficient": $sufficient,
  "counts": {
    "validation_files": $validation_count,
    "decision_entries": $decision_count,
    "event_entries": $event_count,
    "changelog_entries": $changelog_count
  },
  "insufficient_reasons": $(printf '%s\n' "${insufficient_reasons[@]}" | jq -R . | jq -s .)
}
EOF

if [ "$sufficient" != "true" ]; then
    echo "⚠️ INSUFFICIENT DATA for learning:"
    for reason in "${insufficient_reasons[@]}"; do
        echo "   - $reason"
    done
    echo ""
    echo "Returning empty learning report."
fi

Empty Result Handling

**When data is insufficient, return structured empty result:**

{
  "learning_version": "2.1",
  "status": "insufficient_data",
  "timestamp": "2026-01-14T12:00:00Z",
  "data_available": {
    "validation_files": 0,
    "decision_entries": 0,
    "changelog_entries": 0
  },
  "patterns_found": [],
  "skill_adjustments": [],
  "process_improvements": [],
  "evidence_verified": false,
  "notes": "Insufficient data for pattern extraction. Need at least 1 validation and 1 decision."
}

**DO NOT:**

• Guess patterns from assumptions
• Generate improvements without evidence
• Claim learning success with no data

1. Collect Failure Data

# Get recent validation failures
find .self-evolving-loop/reports -name "validation*.json" -exec cat {} \; | \
  jq -s '[.[] | select(.passed == false)]'

# Get decision history
tail -20 .self-evolving-loop/history/decision-log.jsonl | \
  jq -s '[.[] | select(.decision != "SHIP")]'

# Get recent events from the primary log (phase_transition, session_stopped, test/error events)
tail -50 .self-evolving-loop/history/events.jsonl 2>/dev/null | \
  jq -s '[.[] | select((.event // .event_type // "") | test("test_fail|fail|session_stopped"))]'

# Optional secondary: the changelog carries test_fail directly — only read it if it exists
[ -f .director-mode/changelog.jsonl ] && tail -50 .director-mode/changelog.jsonl | \
  jq -s '[.[] | select(.event_type == "test_fail")]'

2. Pattern Recognition

Identify recurring patterns:

## Failure Patterns

### Pattern 1: [Name]
- **Frequency**: N occurrences
- **Symptoms**: [What happens]
- **Context**: [When it happens]
- **Example**: [Specific instance]

### Pattern 2: [Name]
...

Common patterns to look for:

• Same te