claude-reflection

What this skill does

# Claude Reflection Skill

> Meta-skill for continuous self-improvement through the Reflect, Abstract, Generalize, Store loop.

## Quick Start

```bash
# Auto-triggers on detection of:
# - User corrections
# - Preference statements
# - Repeated patterns
# - Positive reinforcement

# Manual trigger for reflection
/claude-reflection

# Review captured learnings
cat ~/.claude/memory/learnings.yaml

# Sync learnings across sessions
/claude-reflection --sync
```

## Overview

The claude-reflection skill enables Claude to learn continuously from user interactions, capturing corrections, preferences, workflow patterns, and positive feedback. Unlike session-scoped context, learnings persist across conversations through structured memory files.

### Why This Matters

**Without reflection:**
- Same mistakes repeated across sessions
- User preferences forgotten
- Valuable patterns lost
- No accumulation of domain knowledge

**With reflection:**
- Corrections learned once, applied forever
- User preferences remembered and applied
- Workflow patterns automated over time
- Domain expertise accumulates across sessions

### Core Philosophy

```
REFLECT    - Notice what happened (correction, preference, pattern)
ABSTRACT   - Extract the generalizable principle
GENERALIZE - Determine scope (global, domain, project, session)
STORE      - Persist to appropriate memory file
```

## When to Use

### Auto-Detection Triggers

This skill auto-executes when it detects these patterns in conversation:

**1. Direct Correction**
```
User: "No, don't use snake_case for that. Use camelCase for JavaScript."
Trigger: Explicit correction of Claude's behavior
Action: Capture coding style preference
```

**2. Preference Statement**
```
User: "I prefer shorter commit messages, just one line."
Trigger: Statement of preference (I prefer, I like, I want, always, never)
Action: Capture workflow preference
```

**3. Explicit Memory Request**
```
User: "Remember that this project uses tabs, not spaces."
Trigger: Direct request to remember (remember, don't forget, always do)
Action: Store as project-level preference
```

**4. Positive Reinforcement**
```
User: "Perfect! That's exactly how I want error messages formatted."
Trigger: Positive feedback on specific behavior
Action: Reinforce and capture the pattern
```

**5. Repeated Patterns**
```
User asks for the same type of change 3+ times in a session
Trigger: Repetition detection
Action: Extract pattern for automation
```

**6. Error-Then-Success**
```
Claude makes mistake -> User corrects -> Claude succeeds
Trigger: Correction followed by success
Action: Capture the correction as a learning
```

### Manual Trigger

```bash
# Force reflection analysis on recent conversation
/claude-reflection

# Reflect on specific topic
/claude-reflection --topic "code formatting"

# Export learnings for review
/claude-reflection --export

# Clear session learnings (keeps persistent)
/claude-reflection --clear-session
```

## Core Process

### The Reflect-Abstract-Generalize-Store Loop

```
                    +------------------+
                    |    DETECTION     |
                    | (correction,     |
                    |  preference,     |
                    |  pattern)        |
                    +--------+---------+
                             |
                             v
+------------------+    +---------+    +------------------+
|     REFLECT      |<---|  Event  |--->|     ABSTRACT     |
| What happened?   |    +---------+    | What's the       |
| What was wrong?  |                   | underlying       |
| What was right?  |                   | principle?       |
+--------+---------+                   +--------+---------+
         |                                      |
         v                                      v
+------------------+                   +------------------+
|   GENERALIZE     |                   |      STORE       |
| What scope?      |                   | Where to save?   |
| Global/Domain/   |                   | What format?     |
| Project/Session  |                   | How to retrieve? |
+--------+---------+                   +------------------+
         |                                      ^
         +--------------------------------------+
```

### Step 1: Reflect

Analyze what happened in the interaction:

```python
# Example reflection analysis
def reflect(interaction: dict) -> dict:
    """Analyze what happened and why."""
    reflection = {
        "event_type": classify_event(interaction),
        "what_happened": interaction["claude_action"],
        "user_response": interaction["user_feedback"],
        "outcome": "correction" | "success" | "preference",
        "confidence": calculate_confidence(interaction)
    }
    return reflection

# Example: User corrected formatting
# {
#     "event_type": "correction",
#     "what_happened": "Used 4-space indentation",
#     "user_response": "Use 2-space indentation for this project",
#     "outcome": "correction",
#     "confidence": 0.95
# }
```

### Step 2: Abstract

Extract the generalizable principle:

```python
# Example abstraction
def abstract_principle(reflection: dict) -> dict:
    """Extract the underlying principle from the reflection."""
    principle = {
        "category": categorize(reflection),  # coding_style, workflow, communication
        "rule": extract_rule(reflection),
        "anti_pattern": reflection.get("what_happened"),
        "correct_pattern": extract_correct_pattern(reflection),
        "context_clues": extract_context(reflection)
    }
    return principle

# Example output:
# {
#     "category": "coding_style",
#     "rule": "Use 2-space indentation",
#     "anti_pattern": "4-space indentation",
#     "correct_pattern": "2-space indentation",
#     "context_clues": ["javascript", "this project"]
# }
```

### Step 3: Generalize

Determine the appropriate scope:

```python
# Example generalization
def determine_scope(principle: dict) -> str:
    """Determine if learning is global, domain, project, or session specific."""

    context_clues = principle.get("context_clues", [])

    # Session-only: temporary, experimental
    if any(word in context_clues for word in ["just this time", "for now", "temporarily"]):
        return "session"

    # Project-specific: mentions project name or "this project"
    if "this project" in context_clues or detect_project_name(context_clues):
        return "project"

    # Domain-specific: mentions technology or domain
    if detect_domain(context_clues):  # javascript, python, marine, etc.
        return "domain"

    # Global: general preference, no specific context
    return "global"

# Example: "this project" -> scope: project
```

### Step 4: Store

Persist the learning appropriately:

```python
# Example storage
def store_learning(principle: dict, scope: str) -> None:
    """Store learning in appropriate memory location."""

    learning_entry = {
        "timestamp": datetime.now().isoformat(),
        "category": principle["category"],
        "rule": principle["rule"],
        "anti_pattern": principle.get("anti_pattern"),
        "correct_pattern": principle["correct_pattern"],
        "confidence": principle.get("confidence", 0.8),
        "source": "user_correction",
        "times_applied": 0
    }

    # Route to appropriate storage
    storage_paths = {
        "global": "~/.claude/memory/global_learnings.yaml",
        "domain": f"~/.claude/memory/domains/{domain}/learnings.yaml",
        "project": ".claude/memory/project_learnings.yaml",
        "session": "session_context"  # Not persisted
    }

    append_to_yaml(storage_paths[scope], learning_entry)
```

## Storage Scopes

### Scope Hierarchy

```
+----------------------------------------------------------+
|  GLOBAL (~/.claude/memory/global_learnings.yaml)         |
|  - User-wide preferences                                  |
|  - Universal coding style                                 |
|  - Communication prefe