retrospective

复盘

交互式会话后复盘。扫描会话，提出有针对性的问题，并给出具体措施供用户一步确认。

模式

单会话模式（在较深入的对话中默认使用）

仅扫描当前对话。这是原有行为。

多会话模式（无参数、使用 “today” 或指定日期时默认使用）

扫描所有项目中指定日期（默认：今天）的全部会话。从 JSONL 转录记录中提取用户纠正、技能失败和模式。

**触发方式：**在新会话开始时输入 /retrospective，或输入 /retrospective today，或 /retrospective 2026-05-24。

多会话发现

步骤 0 — 发现会话

# Find today's sessions (default)
find ~/.claude/projects -maxdepth 2 -name "*.jsonl" -not -path "*/subagents/*" -mtime 0

# Or for a specific date, filter by file modification date
find ~/.claude/projects -maxdepth 2 -name "*.jsonl" -not -path "*/subagents/*" -newermt "YYYY-MM-DD" ! -newermt "YYYY-MM-DD + 1 day"

针对找到的每个 JSONL 文件，提取摘要：

1. 从路径中解析项目名称（projects/ 之后的目录名称，并从路径编码中解码）
2. 提取 user 和 assistant 消息（类型为 user 和 assistant）
3. 对于用户消息：message.content（可以是字符串，也可以是 {type: "text", text: "..."} 数组）
4. 对于助手消息：从 message.content 数组中收集 type == "text" 的文本块
5. 构建精简转录：前 10 条用户消息 + 最后 5 条用户消息（以捕捉结尾处的纠正）
6. 跳过用户消息少于 3 条的会话（太短，无法总结经验）

步骤 0b — 展示会话列表

向用户展示找到的内容：

Found N sessions today:
- project-name-1 (session-id[:8]) — "first user message preview..."
- project-name-2 (session-id[:8]) — "first user message preview..."

然后根据所有会话的综合发现继续执行步骤 1a。每项候选措施都应注明其来源会话（项目名称 + 短 ID）。

单会话流程

步骤 0 — 门槛检查（静默执行）

扫描对话并估计会话的深入程度。留意工具调用（Read、Edit、Write、Bash、技能调用）、遇到的错误以及来回交流。无需精确计数，凭整体感受判断：

• 简短会话（快速问答，约 1–2 项任务）→ 快速模式（步骤 1b）
• 深入会话（多项任务、使用技能、出现错误或纠正）→ 完整模式（步骤 1a）

步骤 1a — 完整模式

静默扫描对话并收集：

1. 调用的技能 — 哪些成功、哪些失败，以及采用了哪些变通方法
2. 用户纠正 — 明确提出“不是这样，请这样做”的时刻（信号最强）
3. 重复模式 — 多次遇到相同错误，或多次采用相同变通方法
4. 跨技能工作流 — 依次串联 3 项或更多技能

然后读取现有状态：

• 查找当前项目的记忆目录：glob ~/.claude/projects/*/memory/MEMORY.md，并读取该文件及相关记忆文件
• 读取所有调用过的技能文件（~/.claude/skills/{name}/skill.md）
• 检查是否存在 Linear CLI：test -f ~/.claude/skills/linear/scripts/linear && echo "configured" || echo "not configured"

生成最多 5 项候选措施，按信号强度排序：

1. 用户纠正（最高优先级）
2. 失败或采用变通方法的技能
3. 重复模式
4. 错误模式
5. 工作流模式（最低优先级）

去重规则：

• 如果候选措施的内容与现有记忆文件重叠 → 丢弃
• 如果技能更新候选项与现有技能文件内容重叠 → 丢弃
• 如果未配置 Linear → 不提供任何 Linear 任务候选项

通过一次 AskUserQuestion 调用呈现所有内容（最多 4 个问题）：

#	问题	类型
1	“快速检查一下本次会话？”	单选：Productive / Mixed / Rough / Skip retro
2	“哪些地方感觉缓慢或出问题了？”	通过 Other 输入的自由文本（可选）
3	“有什么经验需要作为规则保留下来？”	通过 Other 输入的自由文本（可选）
4	“我应该保存哪些内容？”	多选：生成的候选措施及其说明。始终包含“都不保存 / 全部跳过”选项。

如果 Q1 = “Skip retro” → 立即退出。

如果 Q1 = “Rough” 且 Q2/Q3 为空 → 以“没有要保存的内容 — 会话已结束。”退出。用户已经表明要结束，不要再追问。

步骤 1b — 快速模式

调用一次 AskUserQuestion，只提一个问题：

• “本次会话中有什么值得记住的吗？”选项：
  • “没有，结束了”（默认）
  • 其他（自由文本）

如果选择“没有”→ 退出。如果输入自由文本 → 保存为记忆，然后退出。

步骤 2 — 执行（静默，不再确认）

对 Q4 中每个已批准的项目（以及 Q2/Q3 自由文本中的任何见解）：

1. 写入前读取目标文件
2. 检查当前内容中是否存在冲突或重复
3. 如果没有问题，写入更改
4. 如果检测到冲突，跳过并发出警告

操作类型及其目标：

类型	目标	工具
技能更新	~/.claude/skills/{name}/skill.md	Edit
记忆（反馈）	当前项目的 memory/feedback_*.md + MEMORY.md	Write
记忆（项目）	当前项目的 memory/project_*.md + MEMORY.md	Write
CLAUDE.md 规则	~/.claude/CLAUDE.md 或项目 CLAUDE.md	Edit
Linear 任务	~/.claude/skills/linear/scripts/linear issue create --title "..." --description "..."	Bash

步骤 3 — 摘要（简短）

每项已执行操作用一行说明：

Updated telegram skill — added chat type mismatch note
Saved memory — Qwen /api/chat not /api/generate
Skipped: pdf-generation update (already documented)

完成。不添加后续评论。

JSONL 转录格式

会话转录内容以 JSONL 文件的形式存储在 ~/.claude/projects/{project-path}/{session-id}.jsonl。

每一行都是一个带有 type 字段的 JSON 对象。相关类型：

• user — 用户消息。内容位于 message.content（字符串，或由 {type: "text", text: "..."} 组成的数组）
• assistant — Claude 的回复。内容位于 message.content（由内容块组成的数组；提取 type == "text" 的条目）
• ai-title — 自动生成的会话标题

要从 JSONL 文件中提取可读的转录内容，可以使用一行 Python 命令，或读取文件并筛选 user/assistant 类型。

**项目名称解码：**目录名称使用绝对路径，并将斜杠替换为连字符，例如，-Users-glebkalinin-ai-projects-foo → ~/ai_projects/foo。

模式选择逻辑

调用 /retrospective 时：

1. 如果当前对话包含 10 条或更多用户消息 → 单会话模式（回顾本次对话）
2. 如果当前对话较短（只有 /retrospective 调用）→ 多会话模式（扫描今天的会话）
3. 如果参数中包含日期（例如 “today”、“yesterday”、“2026-05-24”）→ 对该日期使用多会话模式
4. 如果参数中包含 “all” → 对今天使用多会话模式

候选项描述格式

Q4 中的每个候选项都必须包含说明，展示确切的拟议内容，而不只是标题。用户是通过阅读说明来判断候选项的，而不是打开文件查看。

好的示例："添加到 telegram 技能：get_chat_type() 会将私聊误判为频道 — 对私信直接使用 Telethon client.send_message()"

不好的示例："更新 telegram 技能以修复私信问题"

此技能不会执行的操作

此技能只记录会话中的经验总结。它不会审查代码质量、分析 PR、创建文档或运行测试。要执行这些操作，请使用相应的专用技能。

规则

• 绝不将经验总结写入此技能文件本身 — 应分发到相关技能或记忆中
• 即使发现更多问题，候选项也最多为 5 个
• 用户纠正的优先级始终高于工具故障
• 步骤 1a 中的多选即表示批准 — 不要再逐项询问
• 如果会话中未使用任何技能，只提供记忆和 CLAUDE.md 候选项
• 整个交互限制为 2 个环节：一次提问，然后静默执行

工具

• AskUserQuestion：交互式提问（每次调用 1–4 个问题，单选/多选）
• Read：提出更改前检查现有记忆和技能文件
• Edit：更新现有技能文件和 CLAUDE.md
• Write：创建新的记忆文件
• Bash：创建 Linear 任务、列出技能目录
• Glob：查找技能和记忆文件

测试

引擎逻辑在 retro_engine.py 中测试，包含 9 个场景夹具和 30 个 pytest 测试。 运行：cd ~/.claude/skills/retrospective && python3 -m pytest test_retro_engine.py -v