Reflect

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 data/signal_patterns.md for full detection rules.

Step 2: Classify & Match to Target Files

Map each signal to the appropriate target:

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

+ New rule from learning

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

Step 5: Apply with User Approval

On `Y` (approve): 1. Apply each change using Edit tool 2. Commit with descriptive message 3. Update metrics

On `N` (reject): 1. Discard proposed changes 2. Log rejection for analysis

On `modify`: 1. Present each change individually 2. Allow editing before applying

On selective (e.g., `1,3`): 1. Apply only specified changes 2. 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

Agent Mappings Reference

Maps learning categories to target agent files for updating.

Agent Directory Structure

~/.claude/agents/
├── universal/
│   ├── backend-developer.md
│   ├── frontend-developer.md
│   └── superstar-engineer.md
├── engineering/
│   ├── api-architect.md
│   ├── architecture-reviewer.md
│   ├── code-reviewer.md
│   ├── security-agent.md
│   ├── test-writer-fixer.md
│   └── ...
├── design/
│   └── ui-designer.md
├── orchestrators/
│   ├── tech-lead-orchestrator.md
│   └── ...
└── meta/
    └── agentmaker.md

Category to Agent Mapping

Code Style

Section in Agent File:

## Code Style
## Style Guidelines
## Heuristics > Style

Architecture

Section in Agent File:

## Architecture Patterns
## Design Patterns
## Heuristics > Architecture

Process

Section in Agent File:

## Workflow
## Process Guidelines
## Heuristics > Process

Domain

Section in Agent File:

## Domain Rules
## Business Logic
## Terminology

Tools

Section in Agent File:

## Tool Usage
## CLI Preferences
## Environment Setup

Security

Section in Agent File:

## Security Heuristics
## Review Heuristics > Security
## Validation Rules

Section Identification

When adding a learning to an agent file, identify the correct section:

Pattern Matching for Sections

## Heuristics
## Style
## Guidelines
## Patterns
## Rules
## Best Practices
## Review Checklist

Section Priority

1. Most specific matching section (e.g., "Security" for security rules) 2. Generic "Heuristics" section 3. "Guidelines" or "Rules" section 4. Create new section if none match

Addition Format

Always add as a bullet point under the appropriate section:

## Heuristics

* Existing rule 1
* Existing rule 2
* **New learning from reflection**  ← Add here

Use bold for newly added rules to distinguish them.

Conflict Detection

Before adding a new rule, check for conflicts:

Contradiction Patterns

# Opposite directives
"never use X" vs "always use X"
"prefer Y" vs "avoid Y"
"use Z" vs "don't use Z"

# Conflicting versions
"use library v1" vs "use library v2"
"Node 18" vs "Node 20"

Resolution Strategy

1. Newer wins: If the new learning contradicts an old rule, flag for review 2. Higher confidence wins: HIGH > MEDIUM > LOW 3. More specific wins: "Never use var in TypeScript" > "Avoid var" 4. User decision: When equal, ask user to resolve

File Paths

Global Agents (User-level)

~/.claude/agents/universal/backend-developer.md
~/.claude/agents/universal/frontend-developer.md
~/.claude/agents/engineering/code-reviewer.md
~/.claude/agents/engineering/api-architect.md
~/.claude/agents/engineering/solution-architect.md
~/.claude/agents/engineering/security-agent.md
~/.claude/agents/engineering/test-writer-fixer.md
~/.claude/agents/design/ui-designer.md

Project Agents (Project-level)

.claude/agents/{name}.md

Global Instructions

~/.claude/CLAUDE.md

Project Instructions

.claude/CLAUDE.md
CLAUDE.md

Skill Creation vs Agent Update

Decide whether to create a new skill or update an agent:

Example Mappings

Example 1: Code Style

Signal: "Never use var in TypeScript, always use const or let" Confidence: HIGH Category: Code Style

Mapping:

• Primary: ~/.claude/agents/universal/frontend-developer.md
• Section: ## Style Guidelines
• Addition: * Use \const\ or \let\ instead of \var\ in TypeScript

Example 2: Architecture

Signal: "Prefer cursor-based pagination for APIs" Confidence: MEDIUM Category: Architecture

Mapping:

• Primary: ~/.claude/agents/engineering/api-architect.md
• Section: ## Design Patterns
• Addition: * Prefer cursor-based pagination over offset-based for large datasets

Example 3: Security

Signal: "Always validate inputs on the server, never trust client validation" Confidence: HIGH Category: Security

Mapping:

• Primary: ~/.claude/agents/engineering/security-agent.md
• Section: ## Validation Rules
• Addition: * Always validate inputs server-side; client validation is for UX only
• Secondary: ~/.claude/agents/engineering/code-reviewer.md
• Section: ## Review Heuristics > Security

Example 4: New Skill

Signal: "Fixed React hydration mismatch by ensuring server and client render same content" Confidence: HIGH Category: New Skill

Mapping:

• Create: .claude/skills/react-hydration-mismatch-fix/SKILL.md
• Include: Error message, symptoms, step-by-step fix, verification

Signal Detection Patterns

Comprehensive reference for detecting correction signals and learning opportunities in conversations.

Confidence Levels

HIGH Confidence (Explicit Corrections)

These patterns indicate the user is explicitly stating a rule or correction. Always apply these learnings.

Negative Directives

Regex Pattern:

\b(never|don't|do not|stop doing|wrong|not like that|incorrect|should not|shouldn't|must not|mustn't)\b

Positive Directives

Regex Pattern:

\b(always|must|required|the rule is|correct way)\b

Frustration Markers

These indicate repeated corrections - highest priority learnings.

Regex Pattern:

(I already told you|again\?|not again|how many times)

Explicit Rules

Regex Pattern:

(the rule is|you should know|remember that|don't forget)

MEDIUM Confidence (Approved Approaches)

These patterns indicate the user approved a specific approach. Apply with reasonable confidence.

Approval Markers

Regex Pattern:

\b(perfect|exactly|that's right|yes, like that|correct)\b

Positive Feedback

Regex Pattern:

\b(good|great job|well done|nice|excellent)\b

Continuation Markers

Regex Pattern:

\b(keep doing|continue with|stick with)\b

LOW Confidence (Observations)

These patterns suggest preferences but require validation before encoding as rules.

Suggestions

Regex Pattern:

\b(maybe|perhaps|might want to|consider)\b

Observations

Regex Pattern:

\b(seems like|appears to|looks like)\b

Category Detection

Code Style

Patterns indicating code style preferences:

\b(naming|convention|style|format|indent|case|camelCase|snake_case|PascalCase)\b
\b(variable|function|class|method|parameter)\s+name
\b(semicolon|quote|single quote|double quote|tabs|spaces)\b

Examples:

• "Use snake_case for Python variables"
• "We prefer single quotes for strings"
• "Indent with 2 spaces, not tabs"

Architecture

Patterns indicating architectural decisions:

\b(pattern|architecture|design|structure|module|component|service)\b
\b(separation|coupling|cohesion|dependency|layer|abstraction)\b
\b(microservice|monolith|serverless|event-driven)\b

Examples:

• "Use dependency injection for services"
• "Keep components loosely coupled"
• "Follow the repository pattern"

Process

Patterns indicating workflow preferences:

\b(workflow|process|step|procedure|protocol|practice)\b
\b(commit|branch|merge|review|deploy|test|ci|cd)\b
\b(pr|pull request|code review|approval)\b

Examples:

• "Always run tests before commit"
• "Use conventional commits"
• "Squash commits on merge"

Domain

Patterns indicating business logic:

\b(business|domain|logic|rule|requirement|constraint)\b
\b(customer|user|client|account|order|payment|invoice)\b
\b(validate|verify|check|ensure|confirm)\b

Examples:

• "Orders must be validated before processing"
• "Users need email verification"
• "Payments require two-factor auth"

Tools

Patterns indicating tool preferences:

\b(tool|cli|command|terminal|shell|editor|ide)\b
\b(git|npm|yarn|pnpm|docker|kubernetes)\b
\b(config|setting|environment|variable|env)\b

Examples:

• "Use pnpm instead of npm"
• "Configure ESLint with these rules"
• "Run Docker in production"

New Skill

Patterns indicating skill-worthy discoveries:

\b(workaround|trick|hack|solution|fix|debug|resolve)\b
\b(error|bug|issue|problem)\s+(was|is|fixed|solved|resolved)\b
(took|spent)\s+\d+\s*(min|minute|hour|day)
\b(finally|after trying|turns out|the issue was)\b

Examples:

• "The workaround is to clear the cache first"
• "After 2 hours debugging, found the issue was..."
• "Turns out the error message was misleading"

Edge Cases

False Positives to Avoid

Some patterns may match but don't indicate learnings:

• Rhetorical questions: "Why would you never do X?" (not a directive)
• Hypotheticals: "If you never use Y, then..." (conditional)
• Quotes/references: "The docs say never..." (not user's directive)
• Negations: "It's not wrong to..." (opposite meaning)

Context Sensitivity

Consider surrounding context:

• "That's not wrong" - NOT a correction
• "That's not right" - IS a correction
• "Never mind" - NOT a directive about future behavior
• "Always" in a loop - NOT a behavioral directive

Combining Patterns

When multiple patterns match:

1. Use the highest confidence pattern 2. If equal confidence, use the most specific category 3. Prefer explicit rules over implied preferences 4. Prioritize frustration markers (indicate repeated issue)

Implementation Notes

The signal_detector.py script implements these patterns. To update patterns:

1. Add pattern to appropriate *_PATTERNS list 2. Run python signal_detector.py --test to verify 3. Add test case for new pattern 4. Update this documentation

Reflect - Agent Self-Improvement Skill

"Correct once, never again."

Transform your AI assistant into a continuously improving partner. The reflect skill analyzes conversations for corrections and successful patterns, permanently encoding learnings into agent definitions.

Features

• Signal Detection: Automatically identifies corrections with confidence levels (HIGH/MEDIUM/LOW)
• Category Classification: Routes learnings to appropriate agent files (Code Style, Architecture, Process, Domain, Tools)
• Skill Generation: Creates new skills from non-trivial debugging discoveries
• Metrics Tracking: Quantifies improvement with acceptance rates and statistics
• Human-in-the-Loop: All changes require explicit approval
• Git Integration: Full version control with easy rollback

Installation

Via ClawdHub CLI

clawdhub install reflect

Manual Installation

Copy the reflect/ folder to your skills directory:

• Claude Code: ~/.claude/skills/reflect/
• Clawdbot: ~/.clawdbot/skills/reflect/

Usage

Basic Reflection

Just say "reflect" or "review session" to trigger analysis:

User: reflect
Agent: [Analyzes conversation, presents learnings for approval]

Toggle Auto-Reflection

User: reflect on
Agent: Auto-reflection enabled. Will analyze before context compaction.

User: reflect off
Agent: Auto-reflection disabled.

Check Status

User: reflect status
Agent:
  Sessions analyzed: 42
  Signals detected: 156
  Changes accepted: 89 (78%)
  Skills created: 5

Review Pending

User: reflect review
Agent: [Shows low-confidence learnings awaiting validation]

How It Works

1. Scan: Analyzes conversation for correction signals 2. Classify: Maps signals to categories and target files 3. Propose: Generates diffs for agent updates or new skills 4. Review: Presents changes for user approval 5. Apply: Commits approved changes with descriptive messages

Signal Detection

Configuration

Set custom state directory:

export REFLECT_STATE_DIR=/path/to/state

Default locations:

• ~/.reflect/ (portable)
• ~/.claude/session/ (Claude Code)

License

MIT

Author

Claude Code Toolkit