| name | loom-brainstorming |
| description | Explore 2-3 implementation options with trade-offs when the user describes a new feature or requirement. Use when: the user asks for a new feature design, implementation options, or technical trade-off analysis.
|
| when_to_use | Explore implementation options, trade-offs, or requirements for a new feature before writing a plan. |
| argument-hint | <feature request or product idea> |
| user-invocable | true |
需求头脑风暴
触发条件
- 用户提出新需求、功能描述或 PRD。
- 用户询问设计方案、实现路径或技术 trade-off。
- 需求存在关键歧义、涉及多角色/权限/业务规则，或验收标准不清。
非触发条件
- 单文件 typo、文案、配置微调或用户已给出明确验收标准的小改动。
- 根因已明确且范围很小的 bug 修复；这类任务应交给
loom-pipeline-selector 命中 quickfix/bugfix 流程。
执行流程
产物根目录
本阶段应创建或使用 specs/<date+feature>/ 作为 specDir。所有阶段产物都必须写入该目录内；禁止在项目根目录写 spec.md、progress.md 或 handoffs/。
Step 1：理解需求
- 若存在
.loom/rules/product.md，先读取，作为产品定位、目标用户和原型约束的视角依据（PM / pm-prototype 流水线）。
- 若存在
.loom/rules/constitution.md，读取其中架构、目录和编码约束。
- 修改类需求先分析现有实现和影响范围。
- 明确边界：做什么、不做什么。
Step 2：可视化伴侣（可选）
如果预计涉及模型、布局、架构图等可视化内容，单独询问用户是否使用浏览器展示。详细流程见 references/visual-companion.md。
Step 3：探索 2-3 种方案
每个方案包含：方案名称、架构思路、数据流、trade-off、实现步骤。以推荐方案开头并解释原因；如果范围跨多个独立子系统，先建议拆分。
Step 4：澄清与 shared understanding
先区分问题来源：能通过读取代码、文档、spec 或现有约定回答的问题，必须先自行探索，不要问用户。
对简单需求，把待决议项集中展示给用户，优先给多选项：
## 待决议项
| # | 问题 | 选项 |
| --- | -------------- | --------------------------------- |
| 1 | 数据存储方式？ | A: 关系型数据库 / B: 文档型数据库 |
对复杂需求进入一问一答澄清：
- 沿最阻塞的设计分支提一个问题。
- 每次只问一个问题。
- 给出推荐答案和理由。
- 等待用户反馈后再问下一个问题。
- 用户确认 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。
不得只生成默认 functional / happy-path。如果需求涉及输入、权限、写操作、状态变化、幂等、并发、外部依赖、安全、性能、可观测性或恢复，必须在 types / required_categories 和 behaviors 中显式体现。
Step 6：Spec 自审
- 占位符：不得残留
TBD、TODO 或未完成段落。
- 一致性：架构、功能、接口、数据模型不能互相矛盾。
- 范围：聚焦单个实现计划；过大时拆分。
- 歧义：有两种解释时选定一种并写清楚。
- 结构化需求：
spec.md 的每个 REQ-xxx 必须出现在 requirements.json，每个 required_categories 必须有对应 behavior。
Step 7：用户审查 Gate
自审通过后让用户审查 spec。用户要求修改时，修复并重新自审；只有用户批准后才继续 writing-plans。
Step 8：阶段交接与压缩
用户批准 spec 后，写入 specs/<date+feature>/handoffs/brainstorming.json，至少包含：
{
"stage": "brainstorming",
"status": "done",
"summary": "已确认的方案和关键取舍摘要",
"artifacts": ["spec.md", "requirements.json"],
"decisions": ["用户已选择的关键方案"],
"open_questions": []
}
阶段结束后压缩 brainstorming 原始讨论、方案比较和搜索输出；下一阶段必须重新读取 specs/<date+feature>/spec.md、specs/<date+feature>/requirements.json、specs/<date+feature>/progress.md、specs/<date+feature>/handoffs/brainstorming.json 和必要规则文件，不依赖旧对话全文。
约束
- 每个方案必须有 trade-off。
- 禁止模糊描述，如"大概"、"可能"、"差不多"。
- 数值必须有单位，如"2 秒内"、"100 条/页"。
- 接口/API 设计必须遵循项目约定。
- YAGNI：删除不必要功能。
- 复杂需求未达成 shared understanding 前，不得进入 planning 或 implementation。
- 不要把可通过代码探索回答的问题转嫁给用户。
完成条件
specs/<date+feature>/spec.md 与 specs/<date+feature>/requirements.json 保存、自审完成、用户批准，并完成 specs/<date+feature>/handoffs/brainstorming.json。
