{"slug":"pdlc-retro","title":"pdlc-retro","summary":"迭代复盘——读状态机历史出趋势报告","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-23T18:54:25.556119Z","repo":{"url":"https://github.com/kanfu-panda/pdlc-skills","stars":15,"forks":2,"license":"MIT","updatedAt":"2026-09-23T15:59:31Z"},"bodyHtml":"
\n

name: pdlc-retro\ndescription: 迭代复盘——读状态机历史出趋势报告\nargument-hint: [--range 7d|30d|all] [--feature

\n\n
\n

PDLC 迭代复盘

\n

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

\n\n

⛔ IRON LAW · 不可违反的硬门禁

\n

以下规则为不可协商的执行约束：

\n
    \n
  1. 文件必须落盘：所有带编号（功能ID / 缺陷ID）的文档，必须作为实际文件写入磁盘，不可仅在对话中输出。
    2. \n
  2. 阶段必须落章：每个阶段完成后必须在状态机 docs/.pdlc-state/<feature-id>.json 追加 history，不可跳过。
    3. \n
  3. 测试必须存在：进入 /pdlc-implement 前，对应测试必须存在且处于红灯状态。违反则中止。
    4. \n
  4. 自检必须执行：段二自检为强制步骤，不得以\"已经很好了\"为由跳过。
    5. \n
  5. 防循环：段三修复为单次，不递归。无法自动修复的问题记录到报告，继续往下走。
    6. \n
  6. 状态必推进：成功执行某 phase 后 current_stage 必须变更。收尾时若发现 current_stage 未推进，视为失败并报错，不得静默返回（防止外层循环拿滞后的状态空转烧额度）。唯一例外：命中人工点主动 block 时，current_stage 保持不变但必须写 last_phase_result.ok=false + blocked_reason。
    7. \n
\n

违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。

\n\n\n

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

\n

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

\n

1. 跑体检

\n

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

\n

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

\n\n

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

\n

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

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
代码判定读侧怎么处理
json-invalid文件不是合法 JSON跳过该文件，列入体检块
missing-field缺 feature_id / current_stage / history / next_step / created_at 之一用到该字段的指标，对这份文件记「不可判」
field-type-invalid字段在、类型不对（如 current_stage 不是字符串、history 不是数组、last_phase_result 不是对象、history 条目不是对象）按缺失处理：用到它的指标对这份文件记「不可判」。类型不对的时间戳不再另报 timestamp-no-time
missing-last_phase_result缺 last_phase_result（多为旧文件）不推断本阶段结果与 checks
terminal_state-in-instance实例里出现 terminal_state忽略该字段，判终态只看 §4
non-contract-field其它表外顶层字段（如 title）忽略
stage-aliasstage 用了已知别名可按说明里的 别名→短名 归一化计数，但必须在体检块写明归一化了哪些
stage-unknownstage 既不是短名也不是已知别名单独成行，不并入任何阶段
current_stage-unknowncurrent_stage 既不是短名，也不以 _done 结尾该功能归入「❓ 异常」
next_step-not-commandnext_step 不是纯命令名（如带散文后缀）按原文展示，不据此推断下一步
timestamp-no-time时间戳只有日期、没有时刻依赖它的耗时类指标记「不可测」，不得算成 0
relations-not-objectrelations 不是六键对象（如数组）这份文件的关系不入图，列入体检块
relations-unknown-type关系键不在六类之内该键下的关系不入图
relations-target-not-id关系目标不是 feature ID（散文、模块路径等）该条不入图
relations-dangling目标 ID 没有对应的状态文件标「悬空」，不参与影响半径计算
id-prefix-mismatch走的是修复流程（有 fix 阶段），ID 却不以 B 开头缺陷计数按 ID 前缀的契约口径算，同时在体检块点名这份
second-state-dir仓库根另有一个 .pdlc-state/本命令只读 docs/.pdlc-state/，提示两处并存
\n\n

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

\n

阶段短名全集

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
短名由哪个命令写入已知别名（读侧可归一化，须披露）
requirementspdlc-prdprd
designpdlc-design
tddpdlc-tdd
implpdlc-implementimplement, implementation
reviewpdlc-review
e2epdlc-e2e
shippdlc-ship
deploypdlc-deploy
fixpdlc-fixbugfix
refactorpdlc-refactor
taskpdlc-task
featurepdlc-feature
\n\n

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

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

4. 判终态的唯一依据 ⛔

\n

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

\n\n\n

段一：聚合统计

\n

1.1 参数解析

\n\n

1.2 读取与过滤

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

1.3 计算指标

\n

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

\n

交付量：

\n\n

质量趋势：

\n\n

阶段耗时：

\n\n

卡点案例：

\n\n

段二：自检

\n\n

段二：自检（强制）

\n

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

\n
\n

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

\n
\n

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

\n

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

\n\n

⚠️ 单次修复原则：若一轮修复后仍有项未通过，不再递归修复，防止死循环。

\n\n

复盘报告自检清单：

\n\n\n

防循环规则

\n

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

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

这是为了防止 agent 在\"修完再查、查完再修\"的往返中陷入死循环。

\n\n

段三：生成报告文件

\n
    \n
  1. 确定输出路径：docs/07_reviews/retro/<YYYY-MM>-retro.md（按当月归档）
    2. \n
  2. 写入模板：
    3. \n
\n
# <YYYY-MM> PDLC 迭代复盘\n\n> 时间窗口：<起> ~ <止>\n> 生成时间：<ISO 时间>\n\n## 输入契约体检\n（仅在体检有偏差或无法体检时出现；按「偏差类 × 份数 × 处理方式」汇总，放在全文最前面）\n\n## 交付量\n- 完成功能：<N> 个\n- 修复缺陷：<M> 个\n\n## 质量趋势\n| 阶段 | 自检通过率 | 平均失败数 | 平均人工介入数 |\n|------|----------|------------|--------------|\n| requirements | XX% | N.N | N.N |\n| design       | XX% | N.N | N.N |\n| tdd          | XX% | N.N | N.N |\n| impl         | XX% | N.N | N.N |\n| review       | XX% | N.N | N.N |\n\n## 阶段耗时中位数\n- 需求: X.Xh  设计: X.Xh  TDD: X.Xh  实现: X.Xh  评审: X.Xh\n  （时间戳缺时刻导致不可测时，写「不可测：<原因>」，不写 0.0h）\n\n## 卡点案例\n- <feature-id> 在 <stage> 阶段: <原因>\n\n## 值得保留的做法\n- <从高通过率/低耗时的功能中提炼>\n
\n
    \n
  1. IRON LAW 落盘：文件必须实际写入磁盘，不可仅在对话中输出
    2. \n
\n

段四：交接

\n\n

段四：交接（Handoff）

\n

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

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

规则：

\n\n\n

本命令的 handoff 输出：

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

参数：$ARGUMENTS

\n","files":[{"path":"scripts/pdlc-state-lint.sh","sizeBytes":11609,"isText":true},{"path":"SKILL.md","sizeBytes":15520,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-23T18:54:57.76064Z","sha256":"7A0C7DC25D3E75AB7F34FCDC7378CF0898F475DA88899EEB91575984FDAEC037","sizeBytes":11977},"review":null,"source":{"repositoryUrl":"https://github.com/kanfu-panda/pdlc-skills","path":"skills/pdlc-retro","license":"MIT","commit":"3cd2f02ab45cb1cd48962e0f298ae4dad9fb442f","subtreeSha":"05EC9771BCFDDB11A4AFEA211D402C1EE7B0BB52845FA6D20C9FA181FD42B6FB","lastSyncedAt":"2026-09-23T18:54:21.123477Z"},"reviewedAt":"2026-09-23T18:56:29.954078Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/kanfu-panda/pdlc-skills/tree/main/skills/pdlc-retro"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kanfu-panda-pdlc-skills@llmmart"},{"target":"git","command":"git clone https://github.com/kanfu-panda/pdlc-skills.git"}]}