.pouch/skills/specifier/references/review-loop.md

HTML PRD 评审闭环

目录

• 状态
• 每轮评审
• 批准
• 批准后的变更

状态

ship current.yaml 的 spec 字段至少记录：

shipId: tenant-permissions
kind: long
spec:
  revision: v002
  specStatus: review
  prd: spec/prd-v002.html
  approvedRevision: null
  reviews: spec/review.yaml

允许的状态：

状态	含义	允许的下一步
draft	已建立需求，但还没形成可审版本	生成 PRD
review	当前版本等待人评审	接收意见或批准
changes_requested	人明确要求修改	生成新版本
approved	指定版本已被明确批准	生成 handoff
handed_off	handoff 已生成并交给 ACK	只能创建后续修订
superseded	版本被后续版本替代	只读历史
parked	用户暂缓	用户恢复后继续评审
rejected	用户明确拒绝	不再自动推进

review.yaml 每轮追加一条记录，不覆盖历史：

- revision: v002
  status: changes_requested
  feedback:
    - section: permissions
      type: decision
      request: "租户管理员不能查看平台级审计日志"
      disposition: applied
  unresolved:
    - id: Q-002
      question: "跨租户查询是否允许平台运维角色使用？"
      owner: user
  changedFrom: v001

不要补写用户没有提供的姓名、时间或审批理由。时间可使用当前环境时间；审批人未知时写 user，不要猜测真实身份。

每轮评审

1. 读取 ship current.yaml、当前 HTML 和所有未解决的 review 项；不要只读用户最新一句话。
2. 将新反馈归类：change、decision、question、rejected、parked。
3. 说明每个反馈对范围、架构、任务和验收的影响。
4. 生成新版本 HTML，保留旧文件。
5. 更新 ship current.yaml 的 spec 字段和 spec/review.yaml，并在回复中给出：新版本路径、变更摘要、未决问题、 是否仍需批准。

如果反馈只影响措辞，也生成新版本；评审记录需要保持可追溯。若用户明确说不采纳，记录理由， 不要悄悄删除意见。

批准

只有以下类型的表达才可作为批准信号：

• “批准 specifier 的 v002 PRD”
• “确认按 v002 开发”
• “需求文档 v002 通过，可以生成 handoff”

批准前必须确认：

• 没有未决的阻塞问题；
• 范围和非目标明确；
• 关键方案和风险已确认；
• 任务都有 expected 和 verification；
• HTML 版本、状态文件和 review 记录一致。

如果用户说“继续”“可以”“看起来不错”，但没有绑定版本，继续保持 review，请用户确认 具体版本。批准后把 spec.approvedRevision 写入 ship current.yaml，再生成 spec/handoff.yaml；不要同时启动 long-ship 或 ACK。

批准后的变更

批准后的需求不能原地编辑。用户提出变化时：

1. 保留已批准版本和 handoff；
2. 将当前状态标为 superseded 或创建新的修订链；
3. 生成下一个 PRD 版本；
4. 标记受影响的任务、验收、风险和 ACK handoff 字段；
5. 重新等待用户批准。

已经进入 long-ship 的任务不会因 HTML 更新而自动改变。需要执行变更时，明确告诉用户应 修订本 ship 的 tasks.yaml 或重新规划，不能静默改写执行记录。