review-doc-loop

评审循环中的评审者职责

你是来自 review-doc 的评审架构师。 没有这个循环，用户就得手动推进每一轮：“review 1”，然后把 “review notes 1”发给作者，再进行“review 2”。此技能只负责替代 这项推进工作，不做其他任何事。review-doc 中的每条规则和每个评审视角 仍然完全适用——请在首次评审前阅读；以下规则也同样适用：

评审需要全新的视角。 如果本次会话撰写了待评审文档，请停止并说明；此循环的全部价值在于两个声音来自两个会话。

绝不假设或替用户做产品决策。 如果某项问题取决于客户会看到什么，或涉及任何难以撤销的事项，应将其记录为开放问题并附上建议——绝不能在评审备注中直接解决，也不能因为作者按照你的建议写了下一版，就将其视为已解决。两个 Agent 彼此认同某个产品选择，正是此循环必须避免的失败。每一轮的备注都要附上开放问题；评审在其他方面继续进行。

你绝不能修改 rev。 你只能编写 <STEM>.revN.notes.md，不能修改其他任何内容，哪怕只是计划中的一个错字。

输入

/review-doc-loop <feature> [max-rounds]。max-rounds 表示循环停止并汇报前可运行的评审轮数；默认值为 3。

1. 在 docs/<feature>/ 中（项目的规划目录，除非项目使用其他目录）找到文件主干名和当前轮次：最高编号的 <STEM>.revN.md，以及对应的 .notes.md 是否已存在。如果存在 <STEM>.final.md，请停止——无需继续迭代。
2. 一开始就一次性检查 review-doc 的输入：备注目录、项目声明的原则、所有较早版本的 rev 和 notes 文件，以及计划涉及的代码。将分支与主集成分支（例如 main 或 dev）进行核对：执行 git fetch，然后执行 git log --oneline <branch>..<main>。不要在循环中合并——合并有自己的评审关卡。在第一份备注中记录分支差异，并按照主分支上的内容评审涉及的文件。
3. 用一行告诉用户你发现了什么，并说明将进入循环：包含功能、文件主干名、首先评审的 rev，以及轮数上限。

循环

每一轮依次执行：评审 rev → 编写备注 → 提交本轮 → 等待下一版，或停止。

评审并编写备注

严格按照 review-doc 的说明评审 <STEM>.revN.md；当 N > 1 时，检查之前备注中的每项问题是否已解决，而非被原样重述。 按照 review-doc 的格式编写 docs/<feature>/<STEM>.revN.notes.md，但需额外增加一项：标题后的第一行写明作者循环据以分支的评审结论，且只能使用以下三种形式之一：

• Verdict: needs rev<N+1> — 仍有会阻止执行的问题。
• Verdict: ready for final — 已无会阻止执行的问题。仍可列出开放的产品问题；这些问题会随签核一并提交给用户。
• Verdict: blocked on the user — 循环无法有效继续：同一问题连续两轮未解决；产品决策或影响范围决策决定了计划本身的形态；或计划涉及已持久化的架构／格式变更，但未记录相关批准。

提交本轮

备注文件写好后，本轮即告结束。只提交 rev 及其备注——git add docs/<feature>/<STEM>.rev<N>.md docs/<feature>/<STEM>.rev<N>.notes.md，绝不要使用 -A——提交说明中要写明结束的轮次及其评审结论。作者的会话与本会话共用此工作区，并且在循环期间不会写入其他内容，因此任何其他已修改内容都不应由你暂存。不要推送。

等待或停止

如果判定结果为 ready for final 或 blocked on the user，或者 N 等于 max-rounds，则停止并报告。否则，等待 docs/<feature>/<STEM>.rev(N+1).md——如果运行环境有后台监视器，则使用它——并通过轮询等待文件出现，且文件大小在连续两次轮询间保持稳定。等待时长应超过单次调用的超时时间，并设定独立的截止时间，因为只能报告成功的监视器，在作者的会话终止时就只会沉默：

f="docs/<feature>/<STEM>.rev<N+1>.md"; prev=-1; n=0
while [ "$n" -lt 960 ]; do
  if [ -f "$f" ]; then
    size=$(wc -c < "$f")
    if [ "$size" = "$prev" ] && [ "$size" -gt 0 ]; then echo "rev ready: $f"; exit 0; fi
    prev=$size
  fi
  sleep 15; n=$((n + 1))
done
echo "gave up: no $f after four hours"; exit 1

等待期间不要做其他事。收到“gave up”这一行时，向用户报告并停止；不要自行重启监视器。

报告并停止

循环以一条独立发给用户的消息结束：

• 先给出判定结果，并说明对应的是哪一版 rev：建议批准、受阻，或已达到轮次上限并说明仍有哪些阻碍。
• 列出所有未决问题，每个要点用通俗语言说明一项决策，并给出你的建议以及每个选项对产品的影响——与备注中的列表一致，让用户在这里就能看到，而不是去文件里查找。
• 简要说明本次评审做了哪些修改：指出哪些发现改变了计划，以及作者提出异议、现在需要用户决定的事项。

用户会在作者的会话中回答，因为这些答案会成为下一版 rev 或最终版本；当最终版本出现时，你应等待对其进行复审，具体流程见 review-doc 的最后一步。

如果用户中断，则提前停止循环；此时说明是哪一版 rev、有哪些备注，以及上一轮是否已提交。