# 需求规格与评审

Roles:

- Analyst
- Reviewer

Analyst 是需求分析师，Reviewer 是评审专家；项目经理即 Boss。
本规程是瀑布流程的需求阶段，把计划与设计合并为一个环节：项目经理给出一项业务需求，Analyst 产出正式的需求规格，经 Reviewer 正式评审后提交，之后才能进入设计与开发。
评审结束前，需求规格只以草稿形式在回复中流转，仓库保持不变；评审结束后，Analyst 一次写入全部文件，并在当前分支上提交为一个 commit。
评审最多两轮。

## 行为

### REQ-1

Analyst 提出澄清问题并等待时，项目经理的答复续接本行为，Analyst 带着答复继续完成草稿。

当项目经理给出一项业务需求时，Captain shall prompt Analyst:

> 你是需求分析师，负责把项目经理给出的业务需求整理为正式的需求规格，提交需求评审。
> 先阅读 specs/（从 specs/map.md 和 specs/meta.md 开始）和相关代码，弄清现有规约、术语和系统现状。
> 如有必须由项目经理澄清才能确定的问题，最多提两个，一次提完，然后等待答复；无需澄清时不要提问。
>
> 按 specs/meta.md 要求的 GEARS 形式编写需求条目：确定条目所属的规约包（specs/packages/ 下已有的包或新增的包），条目编号接续该包现有编号，不与现有条目冲突。
> 每条需求条目只含一个需求，并有可观察的验收条件。
> 术语与现有规约保持一致。
> 考虑异常情形，例如输入不合法、权限不足、外部系统失败或超时。
>
> 按 specs/meta.md 的意图记录格式编写一条意图记录：取下一个未用的编号，文件放在 specs/intents/ 下，写明目标、范围、约束和验收标准。
>
> 评审通过前不要创建或修改任何文件，也不要提交。
> 在回复中给出完整草稿：每个拟写入文件的路径及其完整内容；如新增规约包，也给出 specs/map.md 的相应修改。
> 回复中同时列出你提的澄清问题及项目经理的答复（如有）。
>
> > 业务需求：<caller-input>

Results:
- `drafted`: Analyst 在回复中给出了完整的需求规格草稿，且未修改仓库；进度汇报、状态更新或稍后给出结果的承诺不构成此结果。Output shall include `analystOutput: <verbatim final text>`.

### REQ-2

当 Analyst 给出需求规格草稿、第一轮评审开始时，Captain shall prompt Reviewer:

> 你是评审专家，按正式需求评审的方式评审下方的需求规格草稿。
> 草稿尚未写入仓库；评审对象是下方引用的草稿，对照依据是 specs/（从 specs/map.md 和 specs/meta.md 开始）中的现有规约和相关代码。
> 逐项检查：
> 需求条目是否完整覆盖业务需求；
> 每条需求条目是否只含一个需求，且有可观察、可验证的验收条件；
> 术语是否与现有规约一致；
> 是否有遗漏的异常情形。
> 只提实质性的意见，不提措辞风格或同样可行的其他写法。
> 给出编号的评审意见，每条写明位置、问题和修改建议。
> 没有意见时，明确说明评审通过、没有遗留意见。
> 不要修改文件，也不要提交；只给出评审意见。
>
> > 业务需求：<caller-input>
> > 需求规格草稿：<analyst-output>

Results:
- `hasFindings`: Reviewer 提出了一条或多条评审意见；进度汇报、状态更新或稍后给出结果的承诺不构成任何评审结果，结果也不取决于意见编号或回复的固定格式。Output shall include `reviewerOutput: <verbatim final text>`.
- `noFindings`: Reviewer 明确表示评审通过、没有遗留意见；进度汇报、状态更新或稍后给出结果的承诺不构成任何评审结果，结果也不取决于意见编号或回复的固定格式。Output shall include `reviewerOutput: <verbatim final text>`.

### REQ-3

当 Reviewer 在第一轮评审中提出意见时，Captain shall prompt Analyst:

> 逐条处理下方的评审意见：接受的，修改草稿；不接受的，说明理由。
> 处理时坚持业务需求的原意，并保持需求条目和意图记录符合 specs/meta.md。
> 仍不要创建或修改任何文件，也不要提交。
> 在回复中先列出每条意见的编号、处理结果（接受或不接受）和说明，再给出修订后的完整草稿：每个拟写入文件的路径及其完整内容。
>
> > 第一轮评审意见：<reviewer-output>

Results:
- `revised`: Analyst 逐条给出了处理结果，并在回复中给出了修订后的完整草稿，且未修改仓库；进度汇报、状态更新或稍后给出结果的承诺不构成此结果。Output shall include `analystOutput: <verbatim final text>`.

### REQ-4

当 Analyst 处理完第一轮评审意见、第二轮评审开始时，Captain shall prompt Reviewer:

> 第二轮评审开始，这也是最后一轮评审。
> 先核对 Analyst 对第一轮每条意见的处理：已接受的是否改对；不接受的，认可其理由或坚持该意见并说明原因。
> 再按正式需求评审的方式评审下方修订后的完整草稿；草稿尚未写入仓库，对照依据是 specs/（从 specs/map.md 和 specs/meta.md 开始）中的现有规约和相关代码。
> 逐项检查：
> 需求条目是否完整覆盖业务需求；
> 每条需求条目是否只含一个需求，且有可观察、可验证的验收条件；
> 术语是否与现有规约一致；
> 是否有遗漏的异常情形。
> 只提实质性的意见，不提措辞风格或同样可行的其他写法；不要重复已经解决的意见。
> 给出编号的评审意见，编号接续第一轮，每条写明位置、问题和修改建议。
> 没有意见时，明确说明评审通过、没有遗留意见。
> 不要修改文件，也不要提交；只给出评审意见。
>
> > 业务需求：<caller-input>
> > Analyst 的处理结果与修订草稿：<analyst-output>

Results:
- `hasFindings`: Reviewer 提出或坚持了一条或多条评审意见；进度汇报、状态更新或稍后给出结果的承诺不构成任何评审结果，结果也不取决于意见编号或回复的固定格式。Output shall include `reviewerOutput: <verbatim final text>`.
- `noFindings`: Reviewer 明确表示评审通过、没有遗留意见；进度汇报、状态更新或稍后给出结果的承诺不构成任何评审结果，结果也不取决于意见编号或回复的固定格式。Output shall include `reviewerOutput: <verbatim final text>`.

### REQ-5

当 Reviewer 在第一轮或第二轮评审中表示没有意见时，Captain shall prompt Analyst:

> 需求评审已通过。
> 把评审通过的最终草稿原样写入仓库：意图记录写入 specs/intents/，需求条目写入 specs/packages/ 下相应的规约包；如新增了规约包，按 specs/meta.md 同步更新 specs/map.md。
> 在 docs/reviews/ 下写一份评审记录，文件名与意图记录的文件名相同，记录评审轮次、每轮的每条评审意见及其处理结果，以及评审结论。
> 提交前运行 `npx @sublang/spex lint`，只修正它报告的格式问题，不改变条目的含义。
> 在当前分支上把上述全部文件提交为一个 commit；如有 specs/packages/git.md，提交信息遵循其要求；不要切换或新建分支，不要修改已有的提交。
> 提交后向项目经理报告：commit 哈希、意图编号和需求条目编号列表。
>
> > 评审结论：<reviewer-output>

Results:
- `committed`: Analyst 在当前分支上把意图记录、需求条目和评审记录提交为一个新的 commit，并报告了 commit 哈希、意图编号和需求条目编号列表；此结果下，规程向项目经理返回该 commit 和这份报告。Output shall include `latestCommit: <commit identity>` and `report: <verbatim final text>`.

### REQ-6

当 Reviewer 在第二轮评审中仍提出意见时，Captain shall prompt Analyst:

> 第二轮评审已结束，评审已达两轮上限，不再复审。
> 逐条处理下方的第二轮评审意见：接受的，修改草稿；不接受的，说明理由。
> 然后把处理后的最终草稿写入仓库：意图记录写入 specs/intents/，需求条目写入 specs/packages/ 下相应的规约包；如新增了规约包，按 specs/meta.md 同步更新 specs/map.md。
> 在 docs/reviews/ 下写一份评审记录，文件名与意图记录的文件名相同，记录评审轮次、每轮的每条评审意见及其处理结果，并注明第二轮意见的处理结果未经复审。
> 提交前运行 `npx @sublang/spex lint`，只修正它报告的格式问题，不改变条目的含义。
> 在当前分支上把上述全部文件提交为一个 commit；如有 specs/packages/git.md，提交信息遵循其要求；不要切换或新建分支，不要修改已有的提交。
> 提交后向项目经理报告：commit 哈希、意图编号、需求条目编号列表，以及第二轮每条意见的处理结果，并说明这些处理结果未经复审。
>
> > 第二轮评审意见：<reviewer-output>

Results:
- `committed`: Analyst 处理了第二轮每条评审意见，并在当前分支上把意图记录、需求条目和评审记录提交为一个新的 commit，报告了 commit 哈希、意图编号、需求条目编号列表和第二轮意见的处理结果；此结果下，规程向项目经理返回该 commit 和这份报告。Output shall include `latestCommit: <commit identity>` and `report: <verbatim final text>`.
