coding-retrospect

name	coding-retrospect
description	Use when the user says "轻量复盘", "lite retrospect", "做个复盘", "复盘一下", or after a coding-execute run has completed (goal completed) and wants a quick self-check retrospect on the dev/test process. Produces a lightweight checklist report (changes/retrospect.md, CW retrospect action 入参). 对应 CW action: retrospect. Not for design closeout (that is coding-closeout). Not for planning or execution.

轻量复盘（Retrospect）

对应 CW action: retrospect（coding-workflow tool）。本 skill 产出 changes/retrospect.md， 完成后调 cw(action=retrospect, topicId, retrospectPath) 通过 CW retrospect gate（weak-structural： 文件存在 + 非空）。按 CW 返回的 nextAction 推进（→ closeout）。

核心目标

在一次编码工作流（lite-plan → coding-execute，或 mid-plan → mid-detail-plan → coding-execute）跑完后，用轻量自检清单快速复盘：哪里顺、哪里卡、有什么可改进。不追求结构化证据提取，追求快速发现问题 + 一句话改进建议。

定位：轻量。 不是 coding-closeout（沉淀长期文档），不是 harness-retrospect（重流程质量复盘）。是一张 5 分钟过完的清单，帮下次跑得更好。

前置

• coding-execute 已完成（goal 已 complete，验收全绿）——plan 可来自 lite-plan（plan.md）或 mid-detail-plan/full-execution-plan（execution-plan.md）
• 可选：plan / execution-plan + 测试报告仍在（便于回顾）

流程

单一意图（复盘）：过自检清单 → 根因追溯 → 写报告 → 交付。四步线性推进。

[铁律] 根因追溯是独立步骤，不是清单的一个勾。 清单阶段只产出「哪些 ❌/⚠️ 需深挖」，根因分析在独立 Step 2 用专用判据表做。先打勾后根因、根因与清单条目脱钩的旧做法（只写「问题→改进」不写 why）是已知失败模式——根因与改进建议会脱节，修复停在症状层。

Step 1. 过自检清单

逐项自检，标记 ✅（好）/ ⚠️（需注意）/ ❌（有问题）。清单阶段的产出是「问题清单」——收集所有 ❌/⚠️ 条目（带一句症状描述），根因在 Step 2 分析，本步不强求。 ❌/⚠️ 条目必须保留到 Step 2，不在此处附一句改进建议就标结——没有根因的改进建议是猜。

流程自检

• plan 的 Wave 拆分是否准确？有无返工源于拆分不当（如漏了文件依赖、并行组划错）
• TDD 是否真执行（每个 implementer 先写测试再实现）？还是出现"先写代码后补测试"
• 失败循环触发了几轮？哪轮最耗时？是测试设计问题还是实现问题
• 测试 ‖ review 并行是否真并行了？有无不必要的串行（如 worktree 没建好导致串行跑）

测试质量自检

• 覆盖率是否达标（≥60%）？哪部分增量未覆盖（关键逻辑还是边缘分支）
• E2E 边界用例是否漏了关键场景？有无 bug 是测试没覆盖、验收时才暴露
• plan 的测试清单与实际跑的测试是否一致？有无用例被静默跳过

文档自检

• plan（plan.md / execution-plan.md）是否与最终实现一致？有无偏差（实现改了 plan 没更新）
• 是否需要更新 AGENTS.md / ARCHITECTURE.md / 相关 ADR（本次改动有无影响约定/架构）
• 测试清单是否值得沉淀进 TEST-STRATEGY.md（如有破坏即事故的基线用例）

skill / subagent 优化自检

• 设计 skill（lite-plan / mid-plan / mid-detail-plan）与 coding-execute 的指令是否有歧义导致 AI 跑偏？哪步最模糊
• implementer / test-runner / code-review subagent 的 prompt 和 context 是否足够？有无 NEEDS_CONTEXT / BLOCKED
• subagent 工具白名单是否过严（该有的工具没有）或过松（不该有的给了）

ensemble 趋同数据复盘（仅 lite 产出，消费上次跑的 *_ensemble_overlap）

lite-plan（scope/reuse/test）和 coding-execute（review）在 ensemble 点会产出趋同字段，记在 plan.md / review 清单 frontmatter。本项是这些数据的唯一消费者——读取它们判断哪些 ensemble 点恒定高重合（= 单路已够，未来应降级），让趋同检测真正闭环。否则这些字段是死数据。

mid 不适用：mid 用 review-fix-loop（mid-shared），不产 *_ensemble_overlap 字段。mid 场景此项标「不适用」跳过。

• grep 上次的 *_ensemble_overlap 字段（在 plan.md frontmatter、review 清单、或本 topic 的 _progress.md/retrospect 输入）：
  • 连续 high（≥2 次同类功能都 high overlap）→ 该 ensemble 点单路已够，记改进项「降级 X 为单路」（归属：对应 lite-* skill，方向：删条件触发的 ensemble 分支或默认关）
  • 恒定 low（每次都各找各的）→ 该 ensemble 点同源盲区大，ensemble 价值高，保持
  • 无数据（首次跑 ensemble 或字段缺失）→ 标「数据不足，至少跑 2 次同类功能再判」
• 降级建议若有，进 Step 2 根因追溯（为什么该 ensemble 点恒定高重合——是问题本身简单，还是差异化不够导致 N 路盲区仍相关？）

系统提示词 / 业务 / 架构自检

• 是否有反复出现的错误，提示了 AGENTS.md 或系统提示词需要补充某条规则
• 业务流程是否合理？有无可简化的环节（如某个 Wave 其实可合并、某步验证多余）
• 是否暴露了架构层面的问题（如某模块耦合太紧导致 Wave 无法并行 → 需 full 重构）

Step 2. 根因追溯（独立步骤，对应 Step 1 每条 ❌/⚠️）

对 Step 1 收集的每条 ❌/⚠️，按下表分层判据做根因追溯。这不是可选的深度分析——是复盘的核心价值所在，缺失则复盘仅是症状清单。

根因分层判据表（借鉴 full 的 F/K/D 分层思路）

按「问题归属哪一层」选判据。分层决定修复方向与归属，混层会导向治标不治本：

根因层级	识别信号	修复归属	修复方向
工具/系统层	问题是工具机制限制硬塞给执行者（cwd 不跨调用持久 / subagent 无心跳 / happy-dom 不支持真实 DOM）	pi 调度层 / 业务项目只能绕不能根治	先在 skill 加过渡方案，根治跨 repo
认知/流程层	是 skill 或 agent 的疏漏（handoff 事实盲信 / fixture 不在场 / TDD 步骤跳过）	lite skill / AGENTS.md	改 skill 指令或加规则
架构/契约层	问题源于模块耦合 / 契约不一致 / 测试金字塔断层	业务项目架构 / 需 full 级决策	升级 full 工作流或更新 ADR

每条 ❌/⚠️ 必须产出：症状 → why1 → why2（至少 2 层）→ 分层归类 → 可证伪实验。可证伪 = 能用实验验证（如「若 bash cwd sticky，首条 cd 后 0 次重复」）；不可证伪的根因（如「脚本太脆弱」「AI 太懒」）是错误归因。

常见脱错：①只写「问题→改进」不写 why（根因停在症状）②把认知层问题归给工具（如「漏写 cd」真因是工具 cwd 不 sticky，但「AI 忘了」是误归因——除非 cwd sticky 后仍漏）③把工具层问题归给认知（subagent hang 不是「skill 没写检查」，是系统无 heartbeat——见 subagent-dispatch.md「已知限制」）。分层表防这类误归。

Step 3. 写复盘报告

把清单结果 + 根因分析写入 .xyz-harness/{slug}/retrospect.md（{slug} = CW create slug，与 plan/detail 阶段产出同目录）：

# Lite 复盘：{topic}（{date}）

## 概况
- Wave 数：{N} | 失败循环轮数：{R} | 覆盖率：{X}%
- 总体：✅ 顺利 / ⚠️ 有改进点 / ❌ 有问题

## 清单结果

### 流程
- ✅ Wave 拆分准确
- ❌ TDD 第 2 个 Wave 跳过先写测试 | 根因：症状(skip 跑确认失败)→why1(implementer prompt 未强调该步)→why2(认知层) | 层级：认知层
...

### 测试质量
...

### 文档
...

### skill/subagent
...

### 提示词/业务/架构
...

## 根因深度分析

### 问题 1：{标题}
**症状**：...
**why1**：...
**why2（根因）**：...
**层级**：工具/系统层 | 认知/流程层 | 架构/契约层
**可证伪实验**：若 X 则 Y（如何验证根因真伪）

### 问题 2：...

## 改进项（按优先级）
每条格式：`[P级] 问题 | 根因链(症状→why1→why2) | 层级 | 归属(repo/文件/skill) | 追踪(issue/分支/已修/待办) | 修复方向`

1. [P0] <问题> | 根因：症状→why1→why2 | 层级：认知层 | 归属：lite-plan | 追踪：待办 | 方向：步骤4 加 fixture 对齐自检
2. [P1] ...
3. [P2] ...

轻量：不进长期文档（那是 coding-closeout 的活）。但每条 ❌/⚠️ 必须有根因链 + 层级 + 归属——否则复盘的价值（发现问题）无法转化为改进（修复问题），复盘就成了空转。

[铁律] 报告里每个 ❌/⚠️ 条目后必须附 | 根因：症状→why1→why2 | 层级：xxx。只写「问题→改进」、根因留空 = 未完成复盘，不能进 Step 4 交付。

[铁律] 改进项必须回流，禁止「追踪：待办」死信。 归属为 lite-* / full-* / AGENTS.md 的每条改进项，二选一：

• 当场改对应 skill / 文档，改进项的「追踪」标「已修（文件:行 或 commit）」
• 当场在 docs/todos/ 建 followup 文件（如 docs/todos/lite-skills-followups.md），改进项的「追踪」标 followup 文件路径

只写「追踪：待办」= 未完成复盘。实测：上一轮 retrospect 标了「归属：coding-execute / 追踪：待办」，coding-execute 从未被改，5 条改进全部死信——没有回流机制，retrospect 是自嗨文档。

[提示] retrospect.md 产出在 .xyz-harness/{slug}/，不进代码 commit。 提交代码时用显式路径 git add <改动文件>，禁 git add -A（实测：retrospect.md 被 add -A 误加混进代码 commit）。.xyz-harness/ 是工作流产出，独立于代码变更。

Step 4. 交付

✅ 复盘完成：.xyz-harness/{slug}/retrospect.md
   概况：{N} Wave，{R} 轮失败循环，覆盖率 {X}%
   改进项：{P0 数} 个 P0 / {P1 数} 个 P1
   最值得改：<P0 第一条>

何时升级

复盘若发现架构层面的反复问题（如模块耦合导致并行受限、测试总在某层断裂），建议：

• 走 full 工作流做一次架构设计（coding-init → full-architecture）
• 或更新对应 ADR 记录架构决策

lite 复盘的价值之一：发现"小功能也卡"的根因往往是架构债，这时该升级到 full。

标记说明

标记	含义
✅	做得好，保持
⚠️	需注意，有改进空间
❌	有问题，应改进