solo-retro

/retro

此技能是独立的——请按照以下阶段操作，不要委派给其他技能（/review、/audit、/build），也不要启动 Task 子 Agent。所有分析都直接执行。

流水线后的回顾。解析流水线日志，统计有效与浪费的迭代次数，识别反复出现的失败模式，为本次流水线运行评分，并提出具体的技能/脚本补丁，防止下次重蹈覆辙。

实时上下文

• 分支：!git branch --show-current 2>/dev/null
• 最近的提交：!git log --oneline -10 2>/dev/null
• 已修改文件：!git diff --name-only HEAD~5..HEAD 2>/dev/null | head -20

适用时机

流水线完成（或取消）后使用。这是流程质量检查——/review 检查代码质量，/retro 检查流水线流程质量。

也可独立用于任何项目——无论是否有流水线日志。

MCP 工具（如可用）

• session_search(query) — 查找以往的流水线运行记录和已知问题
• codegraph_explain(project) — 了解项目架构背景
• codegraph_query(query) — 查询代码图谱中的项目元数据

如果 MCP 工具不可用，则改用 Glob + Grep + Read。

阶段 1：定位产物

1. 检测项目：从 $ARGUMENTS 或当前工作目录（CWD）获取：

   • 如果提供了参数：将其用作项目名称
   • 否则：从 CWD 的目录名提取（例如，~/projects/my-app -> my-app）

2. 查找流水线状态文件： .solo/pipelines/solo-pipeline-{project}.local.md（项目本地），或 ~/.solo/pipelines/solo-pipeline-{project}.local.md（全局备用）

   • 如果文件存在：流水线仍在运行或尚未清理——读取 YAML frontmatter 中的 project_root:
   • 如果不存在：流水线已完成——使用 CWD 作为项目根目录

3. 确认产物是否存在（并行读取）：

   • 流水线日志：{project_root}/.solo/pipelines/pipeline.log
   • 迭代日志：{project_root}/.solo/pipelines/iter-*.log
   • 进度文件：{project_root}/.solo/pipelines/progress.md
   • 已完成计划目录：{project_root}/docs/plan-done/
   • 活跃计划：{project_root}/docs/plan/

4. 确定分析模式：

   • 如果流水线日志存在：继续进行基于完整日志的分析（阶段 2-4）
   • 如果没有流水线日志：切换到备用模式（见下文的备用分析）

5. 统计迭代日志（如果存在）：ls {project_root}/.solo/pipelines/iter-*.log | wc -l

   • 报告：“找到 {N} 个迭代日志”

备用分析（没有流水线日志）

如果没有流水线日志，回顾仍可通过分析以下内容提供价值：

1. Git 历史： git log --oneline --since="1 week ago" — 提交频率、模式、是否采用约定格式
2. 测试结果： 如果 CLAUDE.md 或 package.json 中配置了测试套件，则运行测试套件
3. 构建状态： 如果配置了构建，则运行构建
4. CLAUDE.md 变更： git log --oneline -- CLAUDE.md — 文档的演变情况
5. 代码质量指标： 文件数量、TODO/FIXME 密度、死代码迹象
6. 项目结构： docs/、tests/ 和 CI 配置的完整性

跳过阶段 2-4，直接进入阶段 5（计划一致性）和阶段 6（Git 与代码质量）。调整阶段 7 的评分，让可用数据占更大权重。

阶段 2：解析 Pipeline 日志（定量）

完整读取 pipeline.log。逐行解析，从日志标签中提取结构化数据：

日志格式： [HH:MM:SS] TAG | message

按标签提取：

标签	提取内容
START	Pipeline 运行边界——统计重启次数（多条 START 行 = 重启）
STAGE	iter N/M | stage S/T: {stage_id}——每个阶段的迭代次数
SIGNAL	<solo:done/> 或 <solo:redo/>——哪些阶段收到完成信号
INVOKE	调用的技能——提取技能名称，检查名称是否错误
ITER	commit: {sha} | result: {stage complete|continuing}——每次迭代的结果
CHECK	{stage} | {path} -> FOUND|NOT FOUND——标记文件检查
FINISH	Duration: {N}m——每次运行的总时长
MAXITER	Reached max iterations ({N})——是否达到迭代上限
QUEUE	计划循环事件（激活、归档）
CIRCUIT	触发断路器（如有）
CWD	工作目录变更
CTRL	控制信号（暂停/停止/跳过）

计算指标：

total_runs = count of START lines
total_iterations = count of ITER lines
productive_iters = count of ITER lines with "stage complete"
wasted_iters = total_iterations - productive_iters
waste_pct = wasted_iters / total_iterations * 100
maxiter_hits = count of MAXITER lines
plan_cycles = count of QUEUE lines with "Cycling"

per_stage = {
  stage_id: {
    attempts: count of STAGE lines for this stage,
    successes: count of ITER lines with "stage complete" for this stage,
    waste_ratio: (attempts - successes) / attempts * 100,
  }
}

阶段 3：解析 Progress.md（定性）

读取 progress.md 并扫描错误模式：

1. 未知技能错误： 搜索 Unknown skill:——提取错误的技能名称
2. 空迭代： “Last 5 lines” 只显示错误或会话标题（没有实际工作）的迭代
3. 重复错误： 同一错误连续出现在多个迭代中 -> 循环空转指标
4. 重复信号： 同一迭代中出现 <solo:done/><solo:done/> -> 轻微噪声（记录，但不扣分）
5. Redo 循环： 统计 build->review->redo->build 循环发生的次数

对于发现的每种错误模式，记录：

• 模式名称
• 首次出现的位置（迭代编号）
• 总出现次数
• 连续出现次数（最长）

阶段 4：分析 Iter 日志（基于抽样）

不要读取所有 iter 日志——可能有 60 多个。采用智能抽样：

1. 每种模式首次失败的 iter： 对于阶段 3 中发现的每种失败模式，读取首个出现该模式的 iter 日志

   • 读取时去除 ANSI 代码：sed 's/\x1b\[[0-9;]*m//g' < iter-NNN-stage.log | head -100

2. 每个阶段首次成功的 iter： 对于最终成功的每个阶段，读取首个成功的 iter 日志

   • 在输出中查找 <solo:done/>

3. 最终 review iter： 读取最后一个 iter-*-review.log（结论）

4. 从每个抽样日志中提取：

   • 调用的工具（tool_use 块的数量）
   • 遇到的错误（搜索 Error、error、Unknown、failed）
   • 信号输出（是否存在 <solo:done/> 或 <solo:redo/>？）
   • 前 5 行和最后 10 行有意义的内容（跳过空行）

阶段 5：计划执行情况检查

对于 docs/plan-done/ 和 docs/plan/ 中的每个 track 目录：

1. 读取 spec.md（如果存在）：

   • 统计验收标准：- [ ] 和 - [x] 复选框总数
   • 计算：criteria_met = checked / total * 100

2. 读取 plan.md（如果存在）：

   • 统计任务：- [ ] 和 - [x] 复选框总数
   • 统计阶段数（## 标题）
   • 检查 SHA 注释（``）
   • 计算：tasks_done = checked / total * 100

3. 汇总每个 track：

   • Track ID、已满足的标准比例 %、已完成的任务比例 %、是否包含 SHA

阶段 6：Git 和代码质量（轻量检查）

仅进行快速检查——不是完整的 /review：

1. 提交数量和格式：

   git -C {project_root} log --oneline | wc -l
   git -C {project_root} log --oneline | head -30
   

   • 统计符合约定格式的提交（feat:、fix:、chore:、test:、docs:、refactor:、build:、ci:、perf:）
   • 计算：conventional_pct = conventional / total * 100

2. 提交者明细：

   git -C {project_root} shortlog -sn --no-merges | head -10
   

3. 测试状态（如果 CLAUDE.md 或 package.json 中存在测试命令）：

   • 运行测试套件，记录通过/失败数量
   • 如果未找到测试命令，则跳过并注明“未配置测试”

4. 构建状态（如果存在构建命令）：

   • 运行构建，记录成功/失败
   • 如果未找到构建命令，则跳过并注明“未配置构建”

阶段 6.5：上下文退化分析

检查流水线运行期间是否出现上下文窗口问题的迹象：

1. 迭代质量曲线： 对比早期迭代和后期迭代。

   • 错误率是否随时间上升？（上下文退化的迹象）
   • Agent 是否开始重复自己，或跟不上计划？

2. 观察内容屏蔽的使用情况： 检查项目根目录中是否存在 scratch/ 目录。

   • 如果存在：很好——Agent 将大型输出转移到了其他位置
   • 如果不存在，但迭代日志显示工具输出超过 100 行：标记为浪费来源

3. 计划复述证据： 在抽样的迭代日志中，检查 Agent 是否在任务边界处重新阅读了 plan.md。

   • 没有复述且任务偏离 = 上下文工程缺口

4. CLAUDE.md 冗长程度： wc -c {project_root}/CLAUDE.md

   • 超过 40,000 个字符：警告——可能会分散注意力
   • 超过 60,000 个字符：严重——上下文预算压力很大

在报告的 ## Context Health 下添加调查结果：

## Context Health
- Iteration quality trend: {STABLE / DEGRADING / N/A}
- Observation masking: {USED / NOT USED / N/A}
- Plan recitation: {OBSERVED / ABSENT / N/A}
- CLAUDE.md size: {N} chars — {OK / WARN / BLOATED}

阶段 7：评分与报告

从 ${CLAUDE_PLUGIN_ROOT}/skills/retro/references/eval-dimensions.md 加载评分标准。 如果插件根目录不可用，则使用内嵌权重：

评分权重：

• 效率（浪费比例）：25%
• 稳定性（重启次数）：20%
• 保真度（满足的标准）：20%
• 质量（测试通过率）：15%
• 提交（符合规范的比例）：5%
• 文档（计划过时程度）：5%
• 信号（干净信号）：5%
• 速度（每条轨道的耗时，标准化后）：5%

注意： 在备用模式下（没有流水线日志），将效率和稳定性权重重新分配给保真度、质量和提交。

生成报告，保存至 {project_root}/docs/retro/{date}-retro.md：

# Pipeline Retro: {project} ({date})

## Overall Score: {N}/10

## Pipeline Efficiency

| Metric | Value | Rating |
|--------|-------|--------|
| Total iterations | {N} | |
| Productive iterations | {N} ({pct}%) | {emoji} |
| Wasted iterations | {N} ({pct}%) | {emoji} |
| Pipeline restarts | {N} | {emoji} |
| Max-iter hits | {N} | {emoji} |
| Total duration | {time} | {emoji} |
| Tracks completed | {N} | |
| Duration per track | {time/tracks} | {emoji} |

## Per-Stage Breakdown

| Stage | Attempts | Successes | Waste % | Notes |
|-------|----------|-----------|---------|-------|
| scaffold | | | | |
| setup | | | | |
| plan | | | | |
| build | | | | |
| deploy | | | | |
| review | | | | |

## Failure Patterns

### Pattern 1: {name}
- **Occurrences:** {N} iterations
- **Root cause:** {analysis}
- **Wasted:** {N} iterations
- **Fix:** {concrete suggestion with file reference}

### Pattern 2: ...

## Plan Fidelity

| Track | Criteria Met | Tasks Done | SHAs | Rating |
|-------|-------------|------------|------|--------|
| {track-id} | {N}% | {N}% | {yes/no} | {emoji} |

## Code Quality (Quick)

- **Tests:** {N} pass, {N} fail (or "not configured")
- **Build:** PASS / FAIL (or "not configured")
- **Commits:** {N} total, {pct}% conventional format

## Three-Axis Growth

| Axis | Score | Evidence |
|------|-------|----------|
| **Technical** (code, tools, architecture) | {0-10} | {what changed} |
| **Cognitive** (understanding, strategy, decisions) | {0-10} | {what improved} |
| **Process** (harness, skills, pipeline, docs) | {0-10} | {what evolved} |

If only one axis is served — note what's missing.

## Recommendations

1. **[CRITICAL]** {patch suggestion with file:line reference}
2. **[HIGH]** {improvement}
3. **[MEDIUM]** {optimization}
4. **[LOW]** {nice-to-have}

## Suggested Patches

### Patch 1: {file} — {description}

**What:** {one-line description}
**Why:** {root cause reference from Failure Patterns}

\```diff
- old line
+ new line
\```

评级指南（使用以下表情符号）：

• 绿色 = 出色
• 黄色 = 可接受
• 红色 = 需要关注

阶段 8：交互式修补

生成报告后：

1. 向用户展示摘要： 总体得分、排名前三的失败模式、排名前三的建议

2. 针对每个建议的修补（如有），使用 AskUserQuestion：

   • 问题：“将修补应用到 {file}？{one-line description}”
   • 选项：“Apply” / “Skip” / “Show diff first”

3. 如果选择“Show diff first”： 显示完整差异，然后再次询问（Apply / Skip）

4. 如果选择“Apply”： 使用 Edit 工具直接应用更改

5. 处理完所有修补后：

   • 如果应用了任何修补：建议使用 fix(retro): {description} 提交
   • 不要自动提交——只建议执行该命令

阶段 9：修订 CLAUDE.md

修补完成后，修订项目的 CLAUDE.md，使其精简实用，便于后续 Agent 使用。

步骤：

1. 读取 CLAUDE.md 并检查大小：wc -c CLAUDE.md
2. 添加本次复盘的经验：
   • 值得记住的流水线失败模式（避免重蹈覆辙）
   • 新的工作流规则或流程改进
   • 更新后的命令或工具变更
   • 流水线运行期间形成的架构决策
3. 如果超过 40,000 个字符——大幅精简：
   • 将已完成阶段／里程碑的历史压缩为每项一行
   • 删除冗长解释——保留简洁、可执行的备注
   • 删除重复信息（在多个章节中解释同一内容的部分）
   • 删除历史迁移备注和旧调试上下文
   • 删除代码中一目了然或技能／文档文件中已有的示例
   • 删除已解决问题的过时故障排除内容
4. 确认结果不超过 40,000 个字符——如果仍超出，删减最缺乏可执行性的内容
5. 写入更新后的 CLAUDE.md，更新“Last updated”日期

优先级（保留 -> 删除）：

1. 始终保留： 技术栈、目录结构、要做／不要做的规则、常用命令、架构决策
2. 保留： 工作流说明、当前问题的故障排除内容、关键文件引用
3. 精简： 阶段历史（每项一行）、详细示例、工具／MCP 列表
4. 优先删除： 历史备注、冗长解释、重复内容、已解决的问题

规则：

• 绝不删除 Do/Don't 部分——它们是关键防护措施
• 保留整体章节结构和顺序
• 每一行都必须有存在的价值：“未来的 Agent 需要这些内容来完成工作吗？”
• 提交更新：git add CLAUDE.md && git commit -m "docs: revise CLAUDE.md (post-retro)"

阶段 10：工厂评审（可选）

仅在 ${CLAUDE_PLUGIN_ROOT} 可用时运行此阶段（即已安装 solo-factory）。如果作为独立技能运行，且没有工厂上下文，则跳过。

评估完项目流水线后，退一步评估工厂本身——生成此结果的技能、脚本和流水线逻辑。请严厉评审。

评估内容：

1. 阅读本次流水线运行中调用的技能（参见 pipeline.log 中的 INVOKE 行）：

   • 对于每项技能：${CLAUDE_PLUGIN_ROOT}/skills/{stage}/SKILL.md
   • 该技能的指令是否符合此项目的需求？
   • 它是否缺少本应掌握的上下文？

2. 阅读流水线脚本的信号处理和阶段逻辑：

   • ${CLAUDE_PLUGIN_ROOT}/scripts/solo-dev.sh
   • 是否存在结构性问题（阶段顺序错误、缺少重新执行、重做流程失效）？

3. 与阶段 3 中的失败模式交叉参照：

   • 对于每项失败：根本原因在于技能、脚本还是项目？
   • 导致浪费的技能 = 工厂缺陷

为工厂评分（不是为项目评分）：

Factory Score: {N}/10

Skill quality:
- {skill}: {score}/10 — {why}
- {skill}: {score}/10 — {why}

Pipeline reliability: {N}/10 — {why}

Missing capabilities:
- {what the factory couldn't do that it should have}

Top factory defects:
1. {defect} → {which file to fix} → {concrete fix}
2. {defect} → {which file to fix} → {concrete fix}

框架演进——从更宏观的角度思考

为工厂评分后，再退一步思考框架——引导 Agent 的整个系统（CLAUDE.md、docs/、代码检查工具、技能、模板）。请思考：

1. 上下文工程： Agent 在仓库中是否拥有所需的一切？还是因为知识缺失、分散或过时而受阻？

   • 缺少文档 -> 添加到 docs/ 或 CLAUDE.md
   • 文档过时 -> 标记为需要文档整理
   • 只存在于你脑中的知识 -> 将其记录下来

2. 架构约束： Agent 是否破坏了模块边界、采用了不一致的模式，或忽视了约定？

   • 反复违反边界 -> 需要代码检查工具或结构测试
   • 模式不一致 -> 需要在 CLAUDE.md 中确立黄金原则
   • 数据形状错误 -> 需要强制在边界处解析

3. 决策轨迹： 哪些做法效果好，未来的 Agent 应当沿用？哪些做法失败了，应当避免？

   • 好的模式 -> 作为先例记录在 docs 或 CLAUDE.md 中
   • 坏的模式 -> 编码为反模式或代码检查规则
   • 思考：“如果另一个 Agent 明天遇到同样的问题，它应该能找到什么？”

4. 技能缺口： 哪些技能需要更完善的指令？应该新增哪些技能？

   • 导致浪费的技能 -> 对 SKILL.md 提出具体修改
   • 缺少的能力 -> 在演进日志中提出新技能构想

写入演进日志：

将发现追加到 {project_root}/docs/evolution.md（如果不存在则创建）。如果 ~/.solo/evolution.md 存在，也在其中追加，以便跨项目跟踪。

## {YYYY-MM-DD} | {project} | Factory Score: {N}/10

Pipeline: {stages run} | Iters: {total} | Waste: {pct}%

### Defects
- **{severity}** | {skill/script}: {description}
  - Fix: {concrete file:change}

### Harness Gaps
- **Context:** {what knowledge was missing or stale for the agent}
- **Constraints:** {what boundary violations or inconsistencies occurred}
- **Precedents:** {patterns worth capturing for future agents — good or bad}

### Missing
- {capability the factory lacked}

### What worked well
- {skill/pattern that performed efficiently}

规则：

• 绝对坦诚——如果某项技能有问题，就直说
• 每项缺陷都必须有具体修复方案（文件 + 要修改的内容）
• 同时记录有效做法——不要让好的模式退步
• 条目要简洁——此文件会随着时间不断累积

信号输出

输出信号： <solo:done/>

重要： /retro 始终输出 <solo:done/>——它不需要重做。即使流水线糟糕透顶，复盘本身也总能完成。

边缘情况

• **没有 pipeline.log，也没有 Git 历史记录：**中止并显示明确消息——“未找到流水线日志或 Git 历史记录。没有可供分析的内容。”
• **没有 pipeline.log，但有 Git 历史记录：**切换到回退模式（参见回退分析）
• **pipeline.log 为空：**报告“流水线日志为空——流水线是否在任何一次迭代开始前就已取消？”
• **没有迭代日志：**跳过第 4 阶段的抽样，并在报告中注明
• **没有 plan-done：**跳过第 5 阶段，并注明“未找到已完成的计划”
• **没有测试或构建命令：**跳过第 6 阶段中的这些检查，并在报告中注明
• **流水线仍在运行：**向用户发出警告——“状态文件仍存在，流水线可能仍在运行。基于部分数据进行复盘。”

参考文件

• ${CLAUDE_PLUGIN_ROOT}/skills/retro/references/eval-dimensions.md — 评分标准（8 个维度及其权重）
• ${CLAUDE_PLUGIN_ROOT}/skills/retro/references/failure-catalog.md — 已知故障模式及修复方法