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

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:

See signal_patterns.md for full detection rules.

Step 2: Classify & Match to Target Files

Map each signal to the appropriate target:

See 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:

CODEBLOCK0diff
+ New rule from learning
CODEBLOCK1

Step 5: Apply with User Approval

On Y (approve):

1. 1. Apply each change using Edit tool
2. Commit with descriptive message
3. Update metrics

On N (reject):

1. 1. Discard proposed changes
2. Log rejection for analysis

On modify:

1. 1. Present each change individually
2. Allow editing before applying

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

1. 1. Apply only specified changes
2. Commit partial updates

State Management

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

CODEBLOCK2

Metrics Tracking

CODEBLOCK3

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
• INLINECODE21 - New skills

Global (user-level):

• - ~/.reflect/learnings.yaml - Learning log
• INLINECODE23 - 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: INLINECODE27

Proposed change:
CODEBLOCK4

Example 2: Process Preference

User says: "Always run tests before committing"

Signal detected:

• - Confidence: HIGH (explicit "always")
• Category: Process
• Target: INLINECODE28

Proposed change:
CODEBLOCK5

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: INLINECODE29

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