Reflect - Agent Self-Improvement Skill

Transform your AI assistant into a continuously improving partner. Every correction becomes a permanent improvement that persists across all future sessions.

Quick Reference

Command

Action

reflect	Analyze conversation for learnings
reflect on	Enable auto-reflection
reflect off	Disable auto-reflection
reflect status	Show state and metrics
reflect review	Review pending learnings

When to Use

• After completing complex tasks
• When user explicitly corrects behavior ("never do X", "always Y")
• At session boundaries or before context compaction
• When successful patterns are worth preserving

Workflow

Step 1: Scan Conversation for Signals

Analyze the conversation for correction signals and learning opportunities.

Signal Confidence Levels:

Confidence

Triggers

Examples

HIGH	Explicit corrections	"never", "always", "wrong", "stop", "the rule is"
MEDIUM	Approved approaches	"perfect", "exactly", "that's right", accepted output
LOW	Observations	Patterns that worked but not explicitly validated

See data/signal_patterns.md for full detection rules.

Step 2: Classify & Match to Target Files

Map each signal to the appropriate target:

Category

Target Files

Code Style	code-reviewer, backend-developer, frontend-developer
Architecture	solution-architect, api-architect, architecture-reviewer
Process	CLAUDE.md, orchestrator agents
Domain	Domain-specific agents, CLAUDE.md
Tools	CLAUDE.md, relevant specialists
New Skill	Create new skill file

See data/agent_mappings.md for mapping rules.

Step 3: Check for Skill-Worthy Signals

Some learnings should become new skills rather than agent updates:

Skill-Worthy Criteria:

• Non-obvious debugging (>10 min investigation)


• Misleading error (root cause different from message)


• Workaround discovered through experimentation


• Configuration insight (differs from documented)


• Reusable pattern (helps in similar situations)

Quality Gates (must pass all):

• ○Reusable: Will help with future tasks


• ○Non-trivial: Requires discovery, not just docs


• ○Specific: Can describe exact trigger conditions


• ○Verified: Solution actually worked


• ○No duplication: Doesn't exist already

Step 4: Generate Proposals

Present findings in structured format:

# Reflection Analysis

## Session Context
- **Date**: [timestamp]
- **Messages Analyzed**: [count]

## Signals Detected

| # | Signal | Confidence | Source Quote | Category |
|---|--------|------------|--------------|----------|
| 1 | [learning] | HIGH | "[exact words]" | Code Style |

## Proposed Changes

### Change 1: Update [agent-name]
**Target**: `[file path]`
**Section**: [section name]
**Confidence**: HIGH

diff + New rule from learning

## Review Prompt
Apply these changes? (Y/N/modify/1,2,3)

Step 5: Apply with User Approval

On Y (approve):

Apply each change using Edit tool

Commit with descriptive message

Update metrics

On N (reject):

Discard proposed changes

Log rejection for analysis

On modify:

Present each change individually

Allow editing before applying

On selective (e.g., 1,3):

Apply only specified changes

Commit partial updates

State Management

State is stored in ~/.reflect/ (configurable via REFLECT_STATE_DIR):

# reflect-state.yaml
auto_reflect: false
last_reflection: "2026-01-26T10:30:00Z"
pending_reviews: []

Metrics Tracking

# reflect-metrics.yaml
total_sessions_analyzed: 42
total_signals_detected: 156
total_changes_accepted: 89
acceptance_rate: 78%
confidence_breakdown:
  high: 45
  medium: 32
  low: 12
most_updated_agents:
  code-reviewer: 23
  backend-developer: 18
skills_created: 5

Safety Guardrails

Human-in-the-Loop

• NEVER apply changes without explicit user approval
• Always show full diff before applying
• Allow selective application

Incremental Updates

• ONLY add to existing sections
• NEVER delete or rewrite existing rules
• Preserve original structure

Conflict Detection

• Check if proposed rule contradicts existing
• Warn user if conflict detected
• Suggest resolution strategy

Output Locations

Project-level (versioned with repo):

• .claude/reflections/YYYY-MM-DD_HH-MM-SS.md - Full reflection


• .claude/skills/{name}/SKILL.md - New skills

Global (user-level):

• ~/.reflect/learnings.yaml - Learning log


• ~/.reflect/reflect-metrics.yaml - Aggregate metrics

Examples

Example 1: Code Style Correction

User says: "Never use var in TypeScript, always use const or let"

Signal detected:

• Confidence: HIGH (explicit "never" + "always")


• Category: Code Style


• Target: frontend-developer.md

Proposed change:

## Style Guidelines
+ * Use `const` or `let` instead of `var` in TypeScript

Example 2: Process Preference

User says: "Always run tests before committing"

Signal detected:

• Confidence: HIGH (explicit "always")


• Category: Process


• Target: CLAUDE.md

Proposed change:

## Commit Hygiene
+ * Run test suite before creating commits

Example 3: New Skill from Debugging

Context: Spent 30 minutes debugging a React hydration mismatch

Signal detected:

• Confidence: HIGH (non-trivial debugging)


• Category: New Skill


• Quality gates: All passed

Proposed skill: react-hydration-fix/SKILL.md

Troubleshooting

No signals detected:

• Session may not have had corrections


• Check if using natural language corrections

Conflict warning:

• Review the existing rule cited


• Decide if new rule should override


• Can modify before applying

Agent file not found:

• Check agent name spelling


• May need to create agent file first