reflect

# Reflect - Self-Improving Skills

## Overview

This skill enables Claude Code to learn from conversations by analyzing corrections,
approvals, and patterns, then proposing updates to relevant skills. It implements
a "correct once, never again" learning system.

## Usage Modes

### 1. Manual Reflection (/reflect)
Trigger analysis of the current conversation:
```
/reflect [skill-name]
```
- Without skill-name: Analyzes all skills used in conversation
- With skill-name: Focuses on specific skill

### 2. Automatic Reflection
When enabled via `/reflect-on`, runs automatically at session end via Stop hook.

### 3. Toggle Commands
- `/reflect-on` - Enable automatic reflection
- `/reflect-off` - Disable automatic reflection
- `/reflect-status` - Show current configuration

## Confidence Levels

**HIGH** - Explicit corrections:
- User contradicts Claude's approach with specific alternative
- Pattern: "Don't do X, do Y instead"
- Action: Direct updates with deprecation warnings

**MEDIUM** - Approvals and patterns:
- User approves specific approach
- Pattern succeeds multiple times
- Action: Add to "Best Practices" section

**LOW** - Observations:
- User questions or suggests alternatives
- Pattern: "Have you considered..." or "Why not try..."
- Action: Add to "Considerations" section

## Workflow

1. **Signal Detection** - Scan transcript for corrections/patterns
2. **Context Analysis** - Extract 5-message context around signals
3. **Skill Mapping** - Match signals to relevant skills
4. **Change Proposal** - Generate diff of proposed updates
5. **User Review** - Interactive approval with natural language editing
6. **Application** - Safe YAML/markdown updates with backups
7. **Git Commit** - Automatic commit with descriptive message

## Scripts

### Core Engine
- `scripts/reflect.py` - Main orchestration logic
- `scripts/extract_signals.py` - Pattern detection engine
- `scripts/update_skill.py` - Safe skill file updates
- `scripts/present_review.py` - Interactive review interface

### Automation
- `scripts/hook-stop.sh` - Stop hook integration
- `scripts/toggle-on.sh` - Enable auto-reflection
- `scripts/toggle-off.sh` - Disable auto-reflection
- `scripts/toggle-status.sh` - Show status

## Safety Features

- Timestamped backups before all edits
- YAML validation before writing
- Lock files prevent concurrent runs
- Graceful error handling with rollback
- Git status checks before commits

## References

See `references/signal-patterns.md` for detailed pattern library.