PR Lifecycle

把 PR 当作一份持续收敛的契约：先确定系统必须满足什么，再决定由哪些 module 通过哪些 interface 实现；代码、测试和设计报告始终与当前契约一致。

用户的明确要求优先于本 Skill。项目自己的 AGENTS.md、CONTRIBUTING 和仓库规范决定具体命令与交付要求；发现冲突时指出冲突并采用更具体的项目规则。

1. 先区分四类内容

不要把所有决定都叫作 RULE。

SPEC 不是 RULE 的简单集合。完整 SPEC 应包含：

背景与问题
  -> 范围和参与者
  -> 用户场景与可见行为
  -> 产品规则和不变量
  -> 失败、并发与资源语义
  -> 非目标和可接受取舍
  -> 验收标准

RULE 是其中一条局部必须成立的事实。场景、顺序、依赖、失败结果和验收标准把这些 RULE 组织成完整视图。

设计报告负责把 SPEC 中的义务分配给唯一 authority：

• Module：同时拥有 interface 和 implementation 的结构。
• Interface：调用方正确使用 module 必须知道的一切，包括不变量、顺序、错误和性能特征。
• Seam：module interface 所在的位置；行为可以在这里替换而不用修改调用方。
• Authority：最终决定某条规则、状态或错误语义的唯一 module。

算法和存储方案通常是实现机制，不要在没有必要时把它们升级成 SPEC。只要外部契约不变，机制应当可以替换。

2. 生命周期总览

Issue / 用户目标
  -> 事实恢复
  -> Grilling 决策树
  -> SPEC 门禁
  -> 设计门禁
  -> 实现循环
  -> Review -> 修复与验证 -> 再 Review（直到无进一步问题）
  -> 消融与最终一致性审查（有修改或发现问题则回到 Review）
  -> 请求 re-review / 合并

在每个阶段维护三个简短状态：已经确认、当前正在处理、尚未解决。不要因为流程本身阻塞已经获得授权的安全工作；只有尚未确定的产品或设计决定会实质改变结果时，才向用户提问。

3. 阶段 A：恢复事实

编码或评价方案前：

1. 阅读 Issue/SPEC、当前 PR 描述和设计报告。
2. 阅读项目 AGENTS.md、CONTRIBUTING、架构文档、PR 模板和相关验证脚本。
3. 阅读相关 exports、直接 callers/callees、共享 utilities 和现有测试。
4. 查看当前 diff、提交历史、review threads 和 CI 状态；区分当前实现、已废弃中间实现和基线问题。
5. 写下仍然缺失的事实。能从仓库或工具查到的事实自己查，不询问用户。

输出一个短事实摘要：原始问题、当前行为、目标行为、已有约束、未知决策。

4. 阶段 B：用 Grilling 形成 SPEC

当需求存在未决策分支时，使用 grilling Skill；若不可用，则按相同方式分轮追问。Grilling 是发现和确认决策的方法，不是 SPEC 本身。

按依赖顺序遍历决策树：

1. 根问题：用户、问题、成功结果、范围、非目标。
2. 行为分支：主要场景、顺序、不变量、重复操作和状态变化。
3. 异常分支：失败、部分成功、取消、恢复、并发变化。
4. 约束分支：数据规模、资源上限、兼容性、安全和性能。
5. 验收分支：什么证据足以证明每项义务成立。

只有当前置决策确定后，才追问依赖它的下一层。事实由 Agent 查，真正改变产品结果的决定由用户确认。

当决策树的待决前沿为空，并且用户确认双方理解一致时，Grilling 才算结束；在此之前不要把未经确认的选择写成 SPEC 事实。

SPEC 门禁：能够用 references/spec-and-design-template.md 的 SPEC 部分完整描述行为，且每条验收标准都能追溯到一个场景、RULE 或不变量。不能通过门禁时，不要直接选择实现机制。

5. 阶段 C：完成设计报告

先建立 authority 表：

| Rule/state/error/resource | Authority module | Interface/seam | Callers | Evidence |

逐项检查：

• 每条规则是否只有一个 authority？
• 调用方是否在重新推断结果或复制判断？
• source-specific knowledge 是否留在对应 adapter？
• 错误的产生、标准化和展示是否由不同职责清楚承担？
• 资源由谁测量、在哪里限制、超限如何呈现？
• interface 是否暴露了调用方不需要知道的内部机制？
• 删除这个 module 后，复杂度会消失，还是扩散到所有 callers？只有后者说明 module 真正提供了 locality。
• 当前方案是否实现了 SPEC 没要求的更强保证？

然后补全主要数据流、失败流、并发/资源语义、明确取舍和义务到测试的映射。使用 references/spec-and-design-template.md。

设计报告是当前实现契约，不是开发日志。历史决策可以放在 review 回复或单独 decision log 中；最终报告删除废弃机制、迁移设想、一次性脚本和中间版本叙述。

6. 阶段 D：规划和实现

把工作拆成按义务组织的最小切片，而不是按文件或 review comment 组织。

每个切片执行：

1. 重述要满足的 SPEC 义务。
2. 确认 authority 和受影响的 interface。
3. 搜索所有 sibling callers，避免只修一个入口。
4. 在 authority 中实现最小机制。
5. 添加能够在旧行为上失败的最小 owner-level 测试。
6. 仅在真实 seam 上增加必要的集成测试。
7. 同步更新当前设计报告和义务到测试的映射。
8. 运行与本切片成比例的验证。

每个 commit 应表达一个可独立理解的义务、authority 修正或机制替换，并包含必要的代码、测试和设计更新。Commit message 描述结果和原因，不依赖“第几轮 review”的上下文。

出现以下任一信号时暂停叠加补丁并返回设计门禁：

• 一个局部修复引入多个 package 的新状态；
• 新增协议字段、错误码、TTL/LRU、缓存或客户端恢复状态；
• 同一规则出现在两个以上 module；
• 测试必须穿透 interface 才能验证行为；
• 需要大量 UI 文案解释内部生命周期；
• 无法明确说出新增复杂度对应哪条 SPEC 义务。

7. 阶段 E：Review 直到收敛

每轮 review 都针对当前完整 PR diff、相关模块和 SPEC 开展。修复本轮所有确认的问题、同步设计和测试并通过相关验证后，必须继续下一轮 review；修复完成或测试通过本身不能作为结束条件。使用项目约定的 review 方式；若没有约定，主动开展审查，不等待用户再次要求。

先把每条 finding 分类为：

• 功能或正确性错误；
• authority、interface 或 seam 问题；
• 超出 SPEC / 过度设计；
• 测试重复或测试错误对象；
• 设计报告与实现漂移；
• 项目规范或验证问题。

然后执行：

Review 现象
  -> 被违反的 SPEC 义务
  -> 真正 authority
  -> sibling callers 和相邻规则
  -> 最小根因修复
  -> owner-level regression
  -> 设计报告同步

Reviewer 的具体修改建议是重要证据，但不是必须机械执行的代码指令。若建议保护的是超出 SPEC 的更强保证，应说明取舍，选择满足真实义务的最小方案。

每轮结束后进行横向审查：有没有其他 caller 重复同一规则？有没有新机制取代旧机制却未删除旧代码、文案或测试？有没有把 source knowledge 移进共享 core？

Review 循环与结束条件

1. 开展 review，记录本轮重点、发现的问题和证据。核实每条 finding；确认的问题全部修复，不成立或超出 SPEC 的建议说明判断依据。
2. 按上述根因修复流程处理问题，运行相关验证，同步 SPEC、设计报告、代码和测试。尚未解决的问题必须继续保留，不能因为被标记或回复就视为已解决。
3. 只要本轮有修复、测试消融或其他修改，就基于修改后的当前版本再开展一轮 review。下一轮既检查修复是否成立、是否引入新问题，也重新审查完整改动，不能只复查上一轮点名的位置。
4. 持续重复，直到一轮完整 review 没有发现进一步需要解决的问题、此前确认的问题全部关闭，且阶段 F 的最终门禁通过。最终 review 后的任何修改都会使该结束条件失效，需要重新 review。

不要以固定轮数、上一轮问题已修复、CI 通过或“只剩小问题”为理由停止。遇到当前环境无法解决的外部阻塞或真正需要用户决定的契约问题时，明确报告未解决项和所需行动，保持未完成状态，不宣称 review 已收敛。

后续轮次的重点

前一两轮优先覆盖 SPEC、功能正确性、失败语义和回归风险。之后可根据已有发现说明本轮重点，例如：

• 模块权威边界：规则、状态、错误和资源限制是否各有唯一 authority；callers 是否重复推断；interface/seam 是否暴露内部机制；adapter knowledge 是否泄漏到共享 core。
• 过度设计与残留机制：是否加入 SPEC 没要求的保证；新机制是否取代但未删除旧机制；代码、文档和设计报告是否仍描述中间实现。
• 过度测试与测试消融：是否多层重复验证同一规则、测试实现细节、堆积巨大 fixture 或不稳定时序断言；按阶段 F 消融后，最终义务和真实 seam 是否仍有直接、有效的证据。
• 最终一致性与修复影响：SPEC、设计、实现和测试是否一致；上一轮修改是否影响 sibling callers、失败流或资源边界。

重点用于加深审查，不能缩小完整 review 的必要覆盖，也不能把后续轮次变成必须找出新问题的指标。每轮简短说明重点、结果、修复与验证状态，以及是否需要下一轮。

8. 阶段 F：测试消融与最终审查

发生架构调整，或经历两轮以上实质性 review 后，主动执行消融。使用 references/review-and-ablation-checklist.md。本阶段纳入阶段 E 的收敛循环：消融、修复或最终一致性审查带来任何修改后，先验证，再回到阶段 E 重新 review；最终审查发现的问题也必须全部解决并再 review。

为每个最终义务找到最直接的 owner-level 测试，并验证它在破坏该规则时会失败。若多个测试因同一原因失败，优先保留更靠近 authority、更快、更稳定、更能表达意图的测试。

删除或替换：

• 已废弃机制对应的测试；
• 多层重复验证同一 RULE 的测试；
• 只覆盖 reviewer 点名位置、无法覆盖 sibling caller 的测试；
• 修改前就能通过的无效 regression；
• 用巨大 fixture 模拟可注入小上限的测试；
• 用 wall-clock 或进程内存波动证明逻辑有界性的测试。

最终门禁：

1. Issue/SPEC、设计报告、代码和测试一致。
2. 每条规则、状态、错误和资源限制都有唯一 authority。
3. 没有废弃机制、重复推断和过期文档。
4. 每个保留测试都能对应最终义务或真实 seam。
5. 已运行项目要求的 build、format、lint、typecheck 和 tests；未运行或失败的项目被明确报告。
6. PR 摘要保持简洁，并链接详细设计；最终设计报告只描述当前实现。
7. 当前完整改动的最后一轮 review 没有进一步需要解决的问题，此前确认的问题全部关闭，且不存在该轮之后未经再次 review 的修复或消融修改。
8. AI review 只作补充，不替代项目要求的人类 approval。

9. 输出要求

进行中的更新保持简短，说明：已经完成、验证结果、下一项义务。

设计或 review 汇总应优先给出：

1. 当前结论；
2. SPEC 义务；
3. authority/interface 变化；
4. 删除或拒绝的复杂度；
5. 测试证据和未验证项。

不要把开发历史写进最终设计，但要在 review 回复中诚实说明重要设计变化及原因。