PDLC 迭代复盘

读取 docs/.pdlc-state/ 下的状态机历史，按时间范围聚合，生成趋势复盘报告。

<!-- @include templates/prompts/iron-law-tool.md（已内联于下方，无需另读） --> ⛔ IRON LAW · 不可违反的硬门禁（工具型命令）

本命令不是主链路上的阶段：不追加 `history`，不改 `current_stage` / `next_step` / `last_phase_result`，也不为此分配功能ID。以下规则不可协商：

1. 文件必须落盘：正文要求创建的文件必须作为实际文件写入磁盘，不可仅在对话中输出（只要求在对话里输出的，照正文办）。
2. 自检必须执行：产出后按本命令的自检项逐项核对，不得以"已经很好了"为由跳过。
3. 防循环：修复只做一次，不递归。修不了的问题记进报告，继续往下走。

违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。 <!-- @include-end templates/prompts/iron-law-tool.md -->

<!-- @include templates/prompts/state-read.md（已内联于下方，无需另读） -->

读状态机之前：先做契约体检

docs/.pdlc-state/*.json 不一定都是 /pdlc-* 命令写出来的——手写的、旧版本写的、照着格式仿写的 都可能混在里面。字段对不上契约时，不许边猜边算、再把猜出来的东西当结论。先体检，再计算； 体检发现的每一处偏差，都必须出现在输出的最前面。

1. 跑体检

体检脚本随本 skill 一起分发，就在本 skill 目录下：scripts/pdlc-state-lint.sh（运行时会告知本 skill 的 所在目录）。它与正在运行的 skill 同一版本，体检规则——合法阶段名、偏差代码——与下方 §2 一致。

在项目根执行 bash <本 skill 目录>/scripts/pdlc-state-lint.sh .。stdout 每行一条偏差：文件<TAB>代码<TAB>说明。退出码三态：

• 0 已体检、全部合契约 → 照常出结论，不输出体检块
• 1 已体检、有偏差 → 照常计算，但输出最前面必须先放「输入契约体检」块（见 §3）
• 2 无法体检（缺 jq / 无状态目录）→ 体检块写「无法体检：<原因>」，不得当成合契约

体检脚本不可用时（找不到，或当前平台没有随 skill 分发它），按 §2 的规则逐条人工核对， 体检块首行注明「体检脚本不可用，以下为人工核对」。

2. 体检规则（偏差代码）

读侧跳过 _ 前缀的索引文件（如 _relations.json）与 statusline.json，它们不是功能状态机。

<!-- finding-codes:start -->

<!-- finding-codes:end -->

「不入图」不是丢弃：关系目标是散文时，把它硬解读成某个 feature，等于把猜测升格成结构—— 影响半径会因此多出一条本不存在的强依赖。宁可在体检块里原样列出，交给人判断。

#### 阶段短名全集

history[].stage 与 last_phase_result.stage 只能取下表的短名——每个短名由对应命令写入， 等于该命令 frontmatter 的 stage:。别名只为读旧数据时容忍，归一化必须披露；写的时候一律用短名。

<!-- stage-names:start -->

<!-- stage-names:end -->

旧版 /pdlc-task 曾写入 task，现已不写（任务看板不是阶段，写入会覆盖主链路的 current_stage / next_step）。 见到 current_stage=task 说明那次任务操作把功能的阶段盖掉了：体检报 current_stage-unknown，向用户说明后按 history 里最后一个主链路阶段理解进度。

3. 体检块的格式（放在输出最前面）

⚠️ 输入契约体检：<N> 份状态文件，<M> 处偏差——以下结论建立在这些处理之上
  · 3/5 份缺 created_at → 时间窗改用 history 末条 done_at
  · 阶段别名 prd→requirements ×1、implementation→impl ×2 → 已归一化计数
  · 5/5 份含 terminal_state → 已忽略（判终态只看 current_stage）
  · 2 份的 done_at 只有日期 → 阶段耗时记「不可测」

• 按「偏差类 × 份数 × 处理方式」汇总，不要把脚本输出原样倒出来
• 放最前面，不放末尾——结论会被单独引用，偏差得跟着结论走；写在报告末尾的偏差表，

读者看到的时候已经信了前面的数字

• 计数照抄脚本输出，不要自己重数：按代码计数用 cut -f2 | sort | uniq -c，份数按第一列去重。

真机验证时脚本报 25 处无时刻的时间戳，报告正文却自己数成了 26——同一份报告里两个数字对不上， 读者就不知道该信哪个

• 同一次输出里，前面披露了「已忽略 X」，后面的计算就不得再用 X

4. 判终态的唯一依据 ⛔

已抵达终态 ⇔ `current_stage` 以 `_done` 结尾（终态即「已发布」：/pdlc-ship 写 ship_done、/pdlc-deploy 写 deploy_done；旧版本留下的 feature_done / fix_done / review_done 也按终态读）。

• 不看 `terminal_state`。状态机实例本就没有这个字段。skill frontmatter 里的 terminal_state:

说的是「这个命令走完后应当到达的终态名」——是目标，不是事实。拿它判终态， 等于把「打算完成」当成「已经完成」。

• 不用封闭列表（如只认 [feature_done, fix_done]）。封闭列表会把合法的终态漏判成「进行中」，

逼着读侧去别的字段里找答案——而最顺手的那个字段恰好就是 terminal_state。

• `next_step` 为 `null` 也不等于终态：/pdlc-task 写的 next_step 恒为 null，却未必完成；空的或残缺的状态文件也读得出 null。

<!-- @include-end templates/prompts/state-read.md -->

段一：聚合统计

1.1 参数解析

• --range <N>d | all：时间窗口（默认 30d）
• --feature <feature-id>：只看单个功能的时间线（输出 history 详情而非聚合）

1.2 读取与过滤

1. 列出 docs/.pdlc-state/*.json（跳过 _ 前缀的索引文件与 statusline.json）
2. 跑契约体检（见上方「读状态机之前：先做契约体检」），结果写进报告开头的「输入契约体检」节
3. 按 created_at 过滤到时间窗口内。缺 created_at 的文件改用 history 末条 done_at——这是口径替换，必须计入体检块，不得静默
4. 解析每份文件的 history 数组

1.3 计算指标

对时间窗口内的所有功能聚合：

交付量：

• 完成功能数：current_stage 以 _done 结尾——判终态的唯一依据，不看 terminal_state（它是目标不是事实）、不用封闭列表
• 修复缺陷数：feature_id 以 B 开头（契约口径）。体检报 id-prefix-mismatch 的文件在体检块点名，不据此改口径——两个口径打架时，报出来比悄悄挑一个更有用

质量趋势：

• 每阶段自检通过率（passed / (passed + failed + manual)）；某阶段一条自检记录都没有 → 写「无数据」，不写 0%
• 各阶段自检平均 failed、manual 数
• 行按阶段短名：stage-alias 按 别名→短名 归一化后计数（归一化了哪些写进体检块）；stage-unknown 单独成行，不并入任何阶段

阶段耗时：

• 相邻 history 条目的 done_at 差值作为阶段耗时，输出各阶段中位数
• 任一端时间戳没有时刻（体检报 timestamp-no-time）→ 该间隔不可测，不计入中位数；全部不可测 → 整节写「不可测：<原因>」。不得输出 0.0h——它会被读成「快到不耗时」，实际是精度不够

卡点案例：

• 自检 failed > 2 或 manual > 1 的阶段
• 同一阶段耗时 > 3 天的功能

1.4 自动推进的运行记录

状态机只记「走到了哪」，记不下「循环驱动推了几次、在哪被拦、为什么」——这些在驱动的运行记录里。用本 skill 自带的 scripts/pdlc-loop.sh 汇总（只读，不调用模型）：

bash scripts/pdlc-loop.sh --report --since <窗口起点 YYYY-MM-DD> --project <项目根>   # --range all 时不带 --since

• 输出原样放进报告的「自动推进（循环驱动）」节，表里的数字一个都不改、不重算
• 在原样输出下面写 1～3 句解读：哪个阶段被拦得最多、卡点原因里哪一类最多。只说输出里看得到的，不推测原因
• 输出是「没有循环运行记录」→ 该节只写这一句，不算异常
• 脚本跑不了（退出码非 0）→ 该节写「未汇总：<错误>」，不要自己去翻运行记录目录拼数字
• --feature 模式不跑这一步

段二：自检

<!-- @include templates/prompts/self-audit.md（已内联于下方，无需另读） -->

段二：自检（强制）

重新阅读本次产出物，按质量关卡清单逐项检查。勾选已通过，标注未通过原因。

注意：自检清单的具体内容由各命令自行定义，本片段只规定结构。

段三：修复（单次，不递归）

针对自检段标注为未通过的项：

• 可自动修复：直接修复（如补缺字段、修正格式、补齐缺失段落）
• 修复后回验：再次运行自检，确认被修复项现在通过
• 无法自动修复：记录到自审报告，不再尝试，流程继续

⚠️ 单次修复原则：若一轮修复后仍有项未通过，不再递归修复，防止死循环。 <!-- @include-end templates/prompts/self-audit.md -->

复盘报告自检清单：

• [ ] 时间窗口正确（参数解析无误）
• [ ] 数值可加总（交付量、质量趋势）
• [ ] 列出了至少 1 个卡点案例或明确说明"无卡点"
• [ ] 体检有偏差时，报告开头有「输入契约体检」节，且后文计算没有再用已声明忽略的字段（如 terminal_state）
• [ ] 阶段耗时没有把「不可测」写成 0.0h
• [ ] 「自动推进」节是脚本的原样输出（或「没有循环运行记录」/「未汇总：<错误>」），解读没有超出输出里的数字

<!-- @include templates/prompts/loop-prevention.md（已内联于下方，无需另读） -->

防循环规则

本命令所有的自检-修复循环均受以下约束：

1. 单次检查：同一个自检清单在本次命令执行中只跑一次（起始 + 修复后验证共两次读）
2. 单次修复：发现的问题只尝试修复一轮
3. 不递归：修复后不再重新触发自检的全量重跑
4. 失败降级：无法自动修复的问题 → 记录到自审报告 → 流程继续 → 最终报告标注待人工处理

这是为了防止 agent 在"修完再查、查完再修"的往返中陷入死循环。 <!-- @include-end templates/prompts/loop-prevention.md -->

段三：生成报告文件

1. 确定输出路径：docs/07_reviews/retro/<YYYY-MM>-retro.md（按当月归档）
2. 写入模板：

# <YYYY-MM> PDLC 迭代复盘

> 时间窗口：<起> ~ <止>
> 生成时间：<ISO 时间>

## 输入契约体检
（仅在体检有偏差或无法体检时出现；按「偏差类 × 份数 × 处理方式」汇总，放在全文最前面）

## 交付量
- 完成功能：<N> 个
- 修复缺陷：<M> 个

## 质量趋势
| 阶段 | 自检通过率 | 平均失败数 | 平均人工介入数 |
|------|----------|------------|--------------|
| requirements | XX% | N.N | N.N |
| design       | XX% | N.N | N.N |
| tdd          | XX% | N.N | N.N |
| impl         | XX% | N.N | N.N |
| review       | XX% | N.N | N.N |

## 阶段耗时中位数
- 需求: X.Xh  设计: X.Xh  TDD: X.Xh  实现: X.Xh  评审: X.Xh
  （时间戳缺时刻导致不可测时，写「不可测：<原因>」，不写 0.0h）

## 卡点案例
- <feature-id> 在 <stage> 阶段: <原因>

## 自动推进（循环驱动）
（`scripts/pdlc-loop.sh --report` 的原样输出，下面 1～3 句解读；没有运行记录时只写「没有循环运行记录」）

## 值得保留的做法
- <从高通过率/低耗时的功能中提炼>

1. IRON LAW 落盘：文件必须实际写入磁盘，不可仅在对话中输出

段四：交接

<!-- @include templates/prompts/handoff.md（已内联于下方，无需另读） -->

段四：交接（Handoff）

命令完成后必须输出以下格式的最终消息：

✅ <阶段名> 完成：<主要产出物路径>
📊 自检：<通过数>/<总数> 通过（若有未通过，附要点）
📦 状态快照：docs/.pdlc-state/<feature-id>.json
👉 下一步：/pdlc-<next_step>
   （如果有分叉）或 /pdlc-<alt>（条件：<选择依据>）

规则：

• 主流程命令（写状态机的命令；下一跳见正文里「本命令的状态机取值」）必须显式输出"下一步"，不可省略
• 工具型命令（Layer 3）可以没有 next_step，此时输出 👉 下一步：（本次流程结束，无后续）
• 分叉场景必须说明选择条件，例如"若需补充测试用例 → /pdlc-tdd；若测试已齐 → /pdlc-review"

<!-- @include-end templates/prompts/handoff.md -->

本命令的 handoff 输出：

✅ 复盘报告已生成：docs/07_reviews/retro/<YYYY-MM>-retro.md
📊 时间窗口：<起> ~ <止>，共 <N> 个功能
⚠️ 输入契约体检：<M> 处偏差（见报告开头；无偏差则省略本行）
👉 下一步：（本次流程结束，建议人工 review 报告）

参数：$ARGUMENTS