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

---

## 中文说明

# Reflect - 代理自我提升技能

将你的 AI 助手转变为一个持续改进的伙伴。每一次纠正都会成为永久性的改进，并在未来的所有会话中持续生效。

## 快速参考

| 命令 | 操作 |
|---------|--------|
| `reflect` | 分析对话以提取学习内容 |
| `reflect on` | 启用自动反思 |
| `reflect off` | 禁用自动反思 |
| `reflect status` | 显示状态和指标 |
| `reflect review` | 查看待处理的学习内容 |

## 何时使用

- 在完成复杂任务之后
- 当用户明确纠正行为时（"never do X"、"always Y"）
- 在会话边界处或上下文压缩之前
- 当成功的模式值得保留时

## 工作流

### 第 1 步：扫描对话中的信号

分析对话中的纠正信号和学习机会。

**信号置信度等级：**

| 置信度 | 触发条件 | 示例 |
|------------|----------|----------|
| **HIGH** | 明确的纠正 | "never"、"always"、"wrong"、"stop"、"the rule is" |
| **MEDIUM** | 被认可的做法 | "perfect"、"exactly"、"that's right"、被接受的输出 |
| **LOW** | 观察 | 起作用但未被明确验证的模式 |

完整的检测规则参见 [signal_patterns.md](signal_patterns.md)。

### 第 2 步：分类并匹配到目标文件

将每个信号映射到合适的目标：

| 类别 | 目标文件 |
|----------|--------------|
| 代码风格 | `code-reviewer`、`backend-developer`、`frontend-developer` |
| 架构 | `solution-architect`、`api-architect`、`architecture-reviewer` |
| 流程 | `CLAUDE.md`、编排器代理 |
| 领域 | 领域专用代理、`CLAUDE.md` |
| 工具 | `CLAUDE.md`、相关专家代理 |
| 新技能 | 创建新的技能文件 |

映射规则参见 [agent_mappings.md](agent_mappings.md)。

### 第 3 步：检查值得成为技能的信号

有些学习内容应当成为新技能，而非对代理的更新：

**值得成为技能的标准：**
- 非显而易见的调试（调查耗时 >10 分钟）
- 误导性错误（根本原因与提示信息不同）
- 通过实验发现的变通办法
- 配置方面的洞见（与文档记载不同）
- 可复用的模式（在类似情况下有帮助）

**质量关卡（必须全部通过）：**
- [ ] 可复用：将对未来任务有帮助
- [ ] 非琐碎：需要去发现，而非仅查文档
- [ ] 具体：能够描述确切的触发条件
- [ ] 已验证：解决方案确实有效
- [ ] 无重复：尚不存在

### 第 4 步：生成提案

以结构化格式呈现发现：

```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/mod