loom-brainstorming

需求头脑风暴

触发条件

• 用户提出新需求、功能描述或 PRD。
• 用户询问设计方案、实现路径或技术 trade-off。
• 需求存在关键歧义、涉及多角色/权限/业务规则，或验收标准不清。

非触发条件

• 单文件 typo、文案、配置微调或用户已给出明确验收标准的小改动。
• 根因已明确且范围很小的 bug 修复；这类任务应交给 loom-pipeline-selector 命中 quickfix/bugfix 流程。

执行流程

产物根目录

本阶段应创建或使用 specs/<date+feature>/ 作为 specDir。所有阶段产物都必须写入该目录内；禁止在项目根目录写 spec.md、progress.md 或 handoffs/。

Step 1：理解需求

1. 若存在 .loom/rules/product.md，先读取，作为产品定位、目标用户和原型约束的视角依据（PM / pm-prototype 流水线）。
2. 若存在 .loom/rules/constitution.md，读取其中架构、目录和编码约束。
3. 修改类需求先分析现有实现和影响范围。
4. 明确边界：做什么、不做什么。

Step 2：可视化伴侣（可选）

如果预计涉及模型、布局、架构图等可视化内容，单独询问用户是否使用浏览器展示。详细流程见 references/visual-companion.md。

Step 3：探索 2-3 种方案

每个方案包含：方案名称、架构思路、数据流、trade-off、实现步骤。以推荐方案开头并解释原因；如果范围跨多个独立子系统，先建议拆分。

Step 4：澄清与 shared understanding

先区分问题来源：能通过读取代码、文档、spec 或现有约定回答的问题，必须先自行探索，不要问用户。

对简单需求，把待决议项集中展示给用户，优先给多选项：

## 待决议项

| #   | 问题           | 选项                              |
| --- | -------------- | --------------------------------- |
| 1   | 数据存储方式？ | A: 关系型数据库 / B: 文档型数据库 |

对复杂需求进入一问一答澄清：

1. 沿最阻塞的设计分支提一个问题。
2. 每次只问一个问题。
3. 给出推荐答案和理由。
4. 等待用户反馈后再问下一个问题。
5. 用户确认 shared understanding 前，不写最终 spec，不进入实现。

Step 5：输出 spec.md 与 requirements.json

用户确认方案后，写入 specs/<date+feature>/spec.md 和 specs/<date+feature>/requirements.json。文件夹命名格式：<YYYY-MM-DD>+<功能名>，如 2026-04-26+user-management。

使用 assets/spec-template.md 作为结构模板，并按项目类型删去不适用章节。

requirements.json 必须与 spec.md 的所有 REQ-xxx 一一对应。每个 requirement 必须包含：

• id：如 REQ-001。
• status：初始为 failing。
• types：需求类型，如 functional、input、authorization、write、state、security、performance、observable、recovery。
• required_categories：该需求必须覆盖的行为维度，如 happy-path、invalid-input、authorization、atomicity、state-transition、observability。
• acceptance：需求级验收标准。
• behaviors：可独立验证的行为义务，ID 使用 REQ-xxx-Bnn，每条必须有 category、description、status、acceptance。

行为维度必须从以下白名单选择：happy-path、boundary、invalid-input、authorization、state-transition、idempotency、concurrency、atomicity、external-failure、compatibility、security、performance、observability、recovery、forbidden-behavior。