{"skill":{"slug":"reflect-learn","displayName":"Reflect","summary":"Self-improvement through conversation analysis. Extracts learnings from corrections and success patterns, proposes updates to agent files or creates new skil...","description":"---\nname: reflect\ndescription: |\n  Self-improvement through conversation analysis. Extracts learnings from\n  corrections and success patterns, proposes updates to agent files or\n  creates new skills. Philosophy: \"Correct once, never again.\"\n\n  Use when: (1) User explicitly corrects behavior (\"never do X\", \"always Y\"),\n  (2) Session ending or context compaction, (3) User requests /reflect,\n  (4) Successful pattern worth preserving.\nversion: 2.0.0\nauthor: Claude Code Toolkit\nallowed-tools:\n  - Read\n  - Write\n  - Edit\n  - Grep\n  - Glob\n  - Bash\n---\n\n# Reflect - Self-Improvement Skill\n\n## Quick Reference\n\n| Command | Action |\n|---------|--------|\n| `/reflect` | Analyze conversation for learnings |\n| `/reflect on` | Enable auto-reflection |\n| `/reflect off` | Disable auto-reflection |\n| `/reflect status` | Show state and metrics |\n| `/reflect review` | Review low-confidence learnings |\n| `/reflect [agent]` | Focus on specific agent |\n\n## Core Philosophy\n\n**\"Correct once, never again.\"**\n\nWhen users correct behavior, those corrections become permanent improvements encoded into the agent system - across all future sessions.\n\n## Workflow\n\n### Step 1: Initialize State\n\nCheck and initialize state files using the state manager:\n\n```bash\n# Check for existing state\npython scripts/state_manager.py init\n\n# State directory is configurable via REFLECT_STATE_DIR env var\n# Default: ~/.reflect/ (portable) or ~/.claude/session/ (Claude Code)\n```\n\nState includes:\n- `reflect-state.yaml` - Toggle state, pending reviews\n- `reflect-metrics.yaml` - Aggregate metrics\n- `learnings.yaml` - Log of all applied learnings\n\n### Step 2: Scan Conversation for Signals\n\nUse the signal detector to identify learnings:\n\n```bash\npython scripts/signal_detector.py --input conversation.txt\n```\n\n#### Signal Confidence Levels\n\n| Confidence | Triggers | Examples |\n|------------|----------|----------|\n| **HIGH** | Explicit corrections | \"never\", \"always\", \"wrong\", \"stop\", \"the rule is\" |\n| **MEDIUM** | Approved approaches | \"perfect\", \"exactly\", accepted output |\n| **LOW** | Observations | Patterns that worked, not validated |\n\nSee [signal_patterns.md](references/signal_patterns.md) for full detection rules.\n\n### Step 3: Classify & Match to Target Files\n\nMap each signal to the appropriate target:\n\n**Learning Categories:**\n\n| Category | Target Files |\n|----------|--------------|\n| Code Style | `code-reviewer`, `backend-developer`, `frontend-developer` |\n| Architecture | `solution-architect`, `api-architect`, `architecture-reviewer` |\n| Process | `CLAUDE.md`, orchestrator agents |\n| Domain | Domain-specific agents, `CLAUDE.md` |\n| Tools | `CLAUDE.md`, relevant specialists |\n| New Skill | `.claude/skills/{name}/SKILL.md` |\n\nSee [agent_mappings.md](references/agent_mappings.md) for mapping rules.\n\n### Step 4: Check for Skill-Worthy Signals\n\nSome learnings should become new skills rather than agent updates:\n\n**Skill-Worthy Criteria:**\n- Non-obvious debugging (>10 min investigation)\n- Misleading error (root cause different from message)\n- Workaround discovered through experimentation\n- Configuration insight (differs from documented)\n- Reusable pattern (helps in similar situations)\n\n**Quality Gates (must pass all):**\n- [ ] Reusable: Will help with future tasks\n- [ ] Non-trivial: Requires discovery, not just docs\n- [ ] Specific: Can describe exact trigger conditions\n- [ ] Verified: Solution actually worked\n- [ ] No duplication: Doesn't exist already\n\nSee [skill_template.md](references/skill_template.md) for skill creation guidelines.\n\n### Step 5: Generate Proposals\n\nProduce output in this format:\n\n```markdown\n# Reflection Analysis\n\n## Session Context\n- **Date**: [timestamp]\n- **Messages Analyzed**: [count]\n- **Focus**: [all agents OR specific agent name]\n\n## Signals Detected\n\n| # | Signal | Confidence | Source Quote | Category |\n|---|--------|------------|--------------|----------|\n| 1 | [learning] | HIGH | \"[exact words]\" | Code Style |\n| 2 | [learning] | MEDIUM | \"[context]\" | Architecture |\n\n## Proposed Agent Updates\n\n### Change 1: Update [agent-name]\n\n**Target**: `[file path]`\n**Section**: [section name]\n**Confidence**: [HIGH/MEDIUM/LOW]\n**Rationale**: [why this change]\n\n```diff\n--- a/path/to/agent.md\n+++ b/path/to/agent.md\n@@ -82,6 +82,7 @@\n ## Section\n\n * Existing rule\n+* New rule from learning\n```\n\n## Proposed New Skills\n\n### Skill 1: [skill-name]\n\n**Quality Gate Check**:\n- [x] Reusable: [why]\n- [x] Non-trivial: [why]\n- [x] Specific: [trigger conditions]\n- [x] Verified: [how verified]\n- [x] No duplication: [checked against]\n\n**Will create**: `.claude/skills/[skill-name]/SKILL.md`\n\n## Conflict Check\n\n- [x] No conflicts with existing rules detected\n- OR: Warning - potential conflict with [file:line]\n\n## Commit Message\n\n```\nreflect: add learnings from session [date]\n\nAgent updates:\n- [learning 1 summary]\n\nNew skills:\n- [skill-name]: [brief description]\n\nExtracted: [N] signals ([H] high, [M] medium, [L] low confidence)\n```\n\n## Review Prompt\n\nApply these changes?\n- `Y` - Apply all changes and commit\n- `N` - Discard all changes\n- `modify` - Adjust specific changes\n- `1,3` - Apply only changes 1 and 3\n- `s1` - Apply only skill 1\n- `all-skills` - Apply all skills, skip agent updates\n```\n\n### Step 6: Handle User Response\n\n**On `Y` (approve):**\n1. Apply each change using Edit tool\n2. Run `git add` on modified files\n3. Commit with generated message\n4. Update learnings log\n5. Update metrics\n\n**On `N` (reject):**\n1. Discard proposed changes\n2. Log rejection for analysis\n3. Ask if user wants to modify any signals\n\n**On `modify`:**\n1. Present each change individually\n2. Allow editing the proposed addition\n3. Reconfirm before applying\n\n**On selective (e.g., `1,3`):**\n1. Apply only specified changes\n2. Log partial acceptance\n3. Commit only applied changes\n\n### Step 7: Update Metrics\n\n```bash\npython scripts/metrics_updater.py --accepted 3 --rejected 1 --confidence high:2,medium:1\n```\n\n## Toggle Commands\n\n### Enable Auto-Reflection\n\n```bash\n/reflect on\n# Sets auto_reflect: true in state file\n# Will trigger on PreCompact hook\n```\n\n### Disable Auto-Reflection\n\n```bash\n/reflect off\n# Sets auto_reflect: false in state file\n```\n\n### Check Status\n\n```bash\n/reflect status\n# Shows current state and metrics\n```\n\n### Review Pending\n\n```bash\n/reflect review\n# Shows low-confidence learnings awaiting validation\n```\n\n## Output Locations\n\n**Project-level (versioned with repo):**\n- `.claude/reflections/YYYY-MM-DD_HH-MM-SS.md` - Full reflection\n- `.claude/reflections/index.md` - Project summary\n- `.claude/skills/{name}/SKILL.md` - New skills\n\n**Global (user-level):**\n- `~/.claude/reflections/by-project/{project}/` - Cross-project\n- `~/.claude/reflections/by-agent/{agent}/learnings.md` - Per-agent\n- `~/.claude/reflections/index.md` - Global summary\n\n## Memory Integration\n\nSome learnings belong in **auto-memory** (`~/.claude/projects/*/memory/MEMORY.md`) rather than agent files:\n\n| Learning Type | Best Target |\n|---------------|-------------|\n| Behavioral correction (\"always do X\") | Agent file |\n| Project-specific pattern | MEMORY.md |\n| Recurring bug/workaround | New skill OR MEMORY.md |\n| Tool preference | CLAUDE.md |\n| Domain knowledge | MEMORY.md or compound-docs |\n\nWhen a signal is LOW confidence and project-specific, prefer writing to MEMORY.md over modifying agents.\n\n## Safety Guardrails\n\n### Human-in-the-Loop\n- NEVER apply changes without explicit user approval\n- Always show full diff before applying\n- Allow selective application\n\n### Git Versioning\n- All changes committed with descriptive messages\n- Easy rollback via `git revert`\n- Learning history preserved\n\n### Incremental Updates\n- ONLY add to existing sections\n- NEVER delete or rewrite existing rules\n- Preserve original structure\n\n### Conflict Detection\n- Check if proposed rule contradicts existing\n- Warn user if conflict detected\n- Suggest resolution strategy\n\n## Integration\n\n### With /handover\nIf auto-reflection is enabled, PreCompact hook triggers reflection before handover.\n\n### With Session Health\nAt 70%+ context (Yellow status), reminders to run `/reflect` are injected.\n\n### Hook Integration (Claude Code)\n\nThe skill includes hook scripts for automatic integration:\n\n```bash\n# Install hook to your Claude hooks directory\ncp hooks/precompact_reflect.py ~/.claude/hooks/\n```\n\nConfigure in `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreCompact\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"uv run ~/.claude/hooks/precompact_reflect.py --auto\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nSee [hooks/README.md](hooks/README.md) for full configuration options.\n\n## Portability\n\nThis skill works with any LLM tool that supports:\n- File read/write operations\n- Text pattern matching\n- Git operations (optional, for commits)\n\n### Configurable State Location\n\n```bash\n# Set custom state directory\nexport REFLECT_STATE_DIR=/path/to/state\n\n# Or use default\n# ~/.reflect/ (portable default)\n# ~/.claude/session/ (Claude Code default)\n```\n\n### No Task Tool Dependency\n\nUnlike the previous agent-based approach, this skill executes directly without spawning subagents. The LLM reads SKILL.md and follows the workflow.\n\n### Git Operations Optional\n\nCommits are wrapped with availability checks - if not in a git repo, changes are still saved but not committed.\n\n## Troubleshooting\n\n**No signals detected:**\n- Session may not have had corrections\n- Try `/reflect review` to check pending items\n\n**Conflict warning:**\n- Review the existing rule cited\n- Decide if new rule should override\n- Can modify before applying\n\n**Agent file not found:**\n- Check agent name spelling\n- Use `/reflect status` to see available targets\n- May need to create agent file first\n\n## File Structure\n\n```\nreflect/\n├── SKILL.md                      # This file\n├── scripts/\n│   ├── state_manager.py          # State file CRUD\n│   ├── signal_detector.py        # Pattern matching\n│   ├── metrics_updater.py        # Metrics aggregation\n│   └── output_generator.py       # Reflection file & index generation\n├── hooks/\n│   ├── precompact_reflect.py     # PreCompact hook integration\n│   ├── settings-snippet.json     # Settings.json examples\n│   └── README.md                 # Hook configuration guide\n├── references/\n│   ├── signal_patterns.md        # Detection rules\n│   ├── agent_mappings.md         # Target mappings\n│   └── skill_template.md         # Skill generation\n└── assets/\n    ├── reflection_template.md    # Output template\n    └── learnings_schema.yaml     # Schema definition\n```\n","tags":{"latest":"2.1.0"},"stats":{"comments":0,"downloads":8007,"installsAllTime":64,"installsCurrent":64,"stars":14,"versions":2},"createdAt":1769445465505,"updatedAt":1778485857338},"latestVersion":{"version":"2.1.0","createdAt":1771297371403,"changelog":"Add Security category to signal detection, fix agent_mappings.md root-level agents, add Memory integration guidance, consistency fixes across reference files","license":null},"metadata":null,"owner":{"handle":"stevengonsalvez","userId":"s176pqqg1nkg652av8p5a65qfs843qa1","displayName":"Steven Gonsalvez","image":"https://avatars.githubusercontent.com/u/9320602?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779916774127}}