Reflect

# Reflect - Self-Improvement Skill

## 快速参考

| 命令 | 操作 | |---------|--------| | `/reflect` | 分析对话以获取经验 | | `/reflect on` | 启用自动反思 | | `/reflect off` | 禁用自动反思 | | `/reflect status` | 显示状态和指标 | | `/reflect review` | 审查低置信度经验 | | `/reflect [agent]` | 专注于特定代理 |

## 核心理念

**“修正一次，绝不再犯。”**

当用户修正行为时，这些修正将转化为编码到代理系统中的永久性改进——适用于所有未来的会话。

## 工作流程

### 步骤 1：初始化状态

使用状态管理器检查并初始化状态文件：

```bash # Check for existing state python scripts/state_manager.py init

# State directory is configurable via REFLECT_STATE_DIR env var # Default: ~/.reflect/ (portable) or ~/.claude/session/ (Claude Code) ```

状态包括： - `reflect-state.yaml` - 切换状态，待审查项 - `reflect-metrics.yaml` - 聚合指标 - `learnings.yaml` - 所有已应用经验的日志

### 步骤 2：扫描对话以获取信号

使用信号检测器识别经验：

```bash python scripts/signal_detector.py --input conversation.txt ```

#### 信号置信度级别

| 置信度 | 触发条件 | 示例 | |------------|----------|----------| | **高** | 显式修正 | “never”、“always”、“wrong”、“stop”、“the rule is” | | **中** | 认可的方法 | “perfect”、“exactly”、已接受的输出 | | **低** | 观察 | 有效的模式，未经验证 |

有关完整的检测规则，请参阅 [signal_patterns.md](references/signal_patterns.md)。

### 步骤 3：分类并匹配到目标文件

将每个信号映射到相应的目标：

**经验类别：**

| 类别 | 目标文件 | |----------|--------------| | 代码风格 | `code-reviewer`、`backend-developer`、`frontend-developer` | | 架构 | `solution-architect`、`api-architect`、`architecture-reviewer` | | 流程 | `CLAUDE.md`、编排代理 | | 领域 | 特定领域的代理、`CLAUDE.md` | | 工具 | `CLAUDE.md`、相关专家 | | 新技能 | `.claude/skills/{name}/SKILL.md` |

有关映射规则，请参阅 [agent_mappings.md](references/agent_mappings.md)。

### 步骤 4：检查是否具备技能资格

某些经验应成为新技能，而不是代理更新：

**技能资格标准：** - 非显而易见的调试（>10 分钟调查） - 误导性错误（根本原因与消息不同） - 通过实验发现的变通方法 - 配置洞察（与文档不同） - 可重用的模式（在类似情况下有帮助）

**质量标准（必须全部通过）：** - [ ] 可重用：将有助于未来的任务 - [ ] 非平凡：需要发现，而不仅仅是查阅文档 - [ ] 具体：可以描述确切的触发条件 - [ ] 已验证：解决方案确实有效 - [ ] 无重复：尚未存在

有关技能创建指南，请参阅 [skill_template.md](references/skill_template.md)。

### 步骤 5：生成提案

按以下格式生成输出：

```markdown # Reflection Analysis

## Session Context - **Date**: [timestamp] - **Messages Analyzed**: [count] - **Focus**: [all agents OR specific agent name]

## Signals Detected

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

## Proposed Agent Updates

### Change 1: Update [agent-name]

**Target**: `[file path]` **Section**: [section name] **Confidence**: [HIGH/MEDIUM/LOW] **Rationale**: [why this change]

```diff --- a/path/to/agent.md +++ b/path/to/agent.md @@ -82,6 +82,7 @@ ## Section

* Existing rule +* New rule from learning ```

## Proposed New Skills

### Skill 1: [skill-name]

**Quality Gate Check**: - [x] Reusable: [why] - [x] Non-trivial: [why] - [x] Specific: [trigger conditions] - [x] Verified: [how verified] - [x] No duplication: [checked against]

**Will create**: `.claude/skills/[skill-name]/SKILL.md`

## Conflict Check

- [x] No conflicts with existing rules detected - OR: Warning - potential conflict with [file:line]

## Commit Message

``` reflect: add learnings from session [date]

Agent updates: - [learning 1 summary]

New skills: - [skill-name]: [brief description]

Extracted: [N] signals ([H] high, [M] medium, [L] low confidence) ```

## Review Prompt

Apply these changes? - `Y` - Apply all changes and commit - `N` - Discard all changes - `modify` - Adjust specific changes - `1,3` - Apply only changes 1 and 3 - `s1` - Apply only skill 1 - `all-skills` - Apply all skills, skip agent updates ```

### 步骤 6：处理用户响应

**当 `Y`（批准）时：** 1. 使用 Edit 工具应用每个更改 2. 对修改后的文件运行 `git add` 3. 使用生成的消息进行提交 4. 更新经验日志 5. 更新指标

**当 `N`（拒绝）时：** 1. 丢弃建议的更改 2. 记录拒绝情况以供分析 3. 询问用户是否要修改任何信号

**当 `modify`（修改）时：** 1. 单独展示每个更改 2. 允许编辑建议的添加内容 3. 应用前重新确认

**当 selective（选择性，例如 `1,3`）时：** 1. 仅应用指定的更改 2. 记录部分接受情况 3. 仅提交已应用的更改

### 步骤 7：更新指标

```bash python scripts/metrics_updater.py --accepted 3 --rejected 1 --confidence high:2,medium:1 ```

## 切换命令

### 启用自动反思

```bash /reflect on # Sets auto_reflect: true in state file # Will trigger on PreCompact hook ```

### 禁用自动反思

```bash /reflect off # Sets auto_reflect: false in state file ```

### 检查状态

```bash /reflect status # Shows current state and metrics ```

### 审查待处理项

```bash /reflect review # Shows low-confidence learnings awaiting validation ```

## 输出位置

**项目级别（与 repo 一起版本控制）：** - `.claude/reflections/YYYY-MM-DD_HH-MM-SS.md` - 完整反思 - `.claude/reflections/index.md` - 项目摘要 - `.claude/skills/{name}/SKILL.md` - 新技能

**全局（用户级别）：** - `~/.claude/reflections/by-project/{project}/` - 跨项目 - `~/.claude/reflections/by-agent/{agent}/learnings.md` - 每个代理 - `~/.claude/reflections/index.md` - 全局摘要

## 记忆集成

某些经验属于 **自动记忆** (`~/.claude/projects/*/memory/MEMORY.md`)，而不是代理文件：

| 经验类型 | 最佳目标 | |---------------|-------------| | 行为修正（“始终做 X”） | 代理文件 | | 项目特定模式 | MEMORY.md | | 反复出现的错误/变通方法 | 新技能 或 MEMORY.md | | 工具偏好 | CLAUDE.md | | 领域知识 | MEMORY.md 或 复合文档 |

当信号置信度较低且特定于项目时，优先写入 MEMORY.md，而不是修改代理。

## 安全防护

### 人在回路 - 绝不未经用户明确批准即应用更改 - 应用前始终显示完整差异 - 允许选择性应用

### Git 版本控制 - 所有更改都附带描述性消息进行提交 - 通过 `git revert` 轻松回滚 - 保留经验历史

### 增量更新 - 仅添加到现有部分 - 绝不删除或重写现有规则 - 保留原始结构

### 冲突检测 - 检查建议的规则是否与现有规则冲突 - 如果检测到冲突，警告用户 - 建议解决策略

## 集成

### 与 /handover 集成 如果启用了自动反思，PreCompact 钩子将在交接之前触发反思。

### 与会话健康度集成 当上下文达到 70% 以上（黄色状态）时，会注入运行 `/reflect` 的提醒。

### 钩子集成 该技能包含用于自动集成的钩子脚本：

```bash # Install hook to your Claude hooks directory cp hooks/precompact_reflect.py ~/.claude/hooks/ ```

在 `~/.claude/settings.json` 中配置：

```json { "hooks": { "PreCompact": [ { "hooks": [ { "type": "command", "command": "uv run ~/.claude/hooks/precompact_reflect.py --auto" } ] } ] } } ```

有关完整的配置选项，请参阅 [hooks/README.md](hooks/README.md)。

## 可移植性

此技能适用于任何支持以下功能的 LLM 工具： - 文件读/写操作 - 文本模式匹配 - Git 操作（可选，用于提交）

### 可配置的状态位置

```bash # Set custom state directory export REFLECT_STATE_DIR=/path/to/state

# Or use default # ~/.reflect/ (portable default) # ~/.claude/session/ (Claude Code default) ```

### 无任务工具依赖 与以前的基于代理的方法不同，此技能直接执行，无需生成子代理。LLM 读取 SKILL.md 并遵循工作流程。

### Git 操作可选 提交操作包含可用性检查——如果不在 git 仓库中，更改仍会保存，但不会提交。

## 故障排除

**未检测到信号：** - 会话可能没有修正 - 尝试 `/reflect review` 检查待处理项

**冲突警告：** - 查看引用的现有规则 - 确定新规则是否应覆盖 - 可以在应用前修改

**找不到代理文件：** - 检查代理名称拼写 - 使用 `/reflect status` 查看可用目标 - 可能需要先创建代理文件

## 文件结构

``` reflect/ ├── SKILL.md # This file ├── scripts/ │ ├── state_manager.py # State file CRUD │ ├── signal_detector.py # Pattern matching │ ├── metrics_updater.py # Metrics aggregation │ └── output_generator.py # Reflection file & index generation ├── hooks/ │ ├── precompact_reflect.py # PreCompact hook integration │ ├── settings-snippet.json # Settings.json examples │ └── README.md # Hook configuration guide ├── references/ │ ├── signal_patterns.md # Detection rules │ ├── agent_mappings.md # Target mappings │ └── skill_template.md # Skill generation └── assets/ ├── reflection_template.md # Output template └── learnings_schema.yaml # Schema definition ```