Reflect Skill

Analyze conversations to extract corrections, preferences, and best practices, then persist them to skill files. Supports manual triggering, automatic hooks, and Git versioning.

Commands

Command	Description
/reflect	Analyze current session and propose skill updates
/reflect [skill-name]	Reflect and update a specific skill
reflect on	Enable automatic reflection via stop hook
reflect off	Disable automatic reflection
reflect status	Show current reflection mode

Manual Reflection Flow

1. Analyze Session for Signals

Scan the conversation and categorize by confidence:

HIGH Confidence - Explicit corrections

• "No, use X instead of Y"
• "Never [action] in this project"
• "Always check for [condition]"

MEDIUM Confidence - Success patterns

• Approaches that worked after iteration
• Patterns user approved or praised

LOW Confidence - Observations

• Implied preferences
• Patterns to review later

2. Present Review & Approval

📊 Signals Detected:

HIGH CONFIDENCE:
- "Never generate button styles - reference existing components"
- "Always check for SQL injections"

MEDIUM CONFIDENCE:
- Arrow functions preferred for callbacks

LOW CONFIDENCE:
- Prefers concise explanations

📝 Proposed Changes to [skill-name].md:

+ ## Security
+ - Always validate database queries for SQL injection
+
+ ## Code Style  
+ - Never generate UI components; reference existing library

💬 Commit message: "Add SQL injection and UI component rules"

Accept changes? [Y/n/edit with natural language]

User options:

• Y - Accept all changes
• n - Reject
• Natural language: "Remove the arrow function one" or "Change the wording to..."

3. Update Skill & Commit

1. Locate target skill file (project or ~/.claude/skills/)
2. Merge new learnings (newer rules override conflicts)
3. If Git repo: stage, commit with message, push

Automatic Reflection

Toggle Commands

reflect on      # Enable auto-reflection on session end
reflect off     # Disable auto-reflection
reflect status  # Check current mode

How It Works

When enabled, the stop hook triggers automatic learning:

1. Session ends → stop hook fires
2. Analyzes conversation for learnings
3. Updates skill file (shows notification: "Learned from session: [skill-name]")
4. Commits to Git if configured

Hook Configuration

The session-end hook is auto-registered when you install this plugin. No manual configuration needed.

State stored in ~/.claude/.reflect-state (enabled/disabled).

Git Integration

Version your skills to track evolution over time:

cd ~/.claude/skills
git init
git remote add origin <your-repo>

Benefits:

• See how skills evolve with each learning
• Rollback if a learning causes regressions
• Track system improvement over time

Learning Categories

Category	Examples
Code Style	Naming conventions, formatting
Security	Input validation, SQL injection
Testing	Coverage requirements, edge cases
API Design	Endpoint conventions, responses
UI/UX	Component usage, accessibility
Workflow	PR process, commit format

Example

You: Review the auth module
Claude: [Reviews, misses SQL injection]
You: You missed SQL injection - always check for that

You: /reflect

Claude: 📊 HIGH: "Always check for SQL injections"
        
        📝 Proposed for security-review.md:
        + - Validate all database queries for SQL injection
        
        Accept? [Y/n]

You: Y

Claude: ✅ Updated security-review.md
        📤 Committed: "Add SQL injection validation rule"

Next session: Claude automatically checks for SQL injection.

Goal

Correct once, never again. Build a self-improving system where learnings persist and compound over time.