self-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 | 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 [signal_patterns.md](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 [agent_mappings.md](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: ```markdown # 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):** 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`): ```yaml # reflect-state.yaml auto_reflect: false last_reflection: "2026-01-26T10:30:00Z" pending_reviews: [] ``` ### Metrics Tracking ```yaml # 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**: ```diff ## 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**: ```diff ## 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