trellis-brainstorm

Trellis 头脑风暴

不可妥协的规划约定

要求构建、实现、修复、重构或“继续”的请求，并不代表获准结束规划。创建任务的同意也不代表获准开始实现。

对于每一项非琐碎任务，必须在初始请求之后至少收到用户的一次回复，才能开始实现。如果无需澄清，该回复必须批准下文所述的最终规划摘要。

只要仍有任何由用户决定的产品、范围、UX、兼容性、风险或验收事项尚未解决，就在本轮结束时只提出一个价值最高的问题。不得编辑产品代码、派发实现工作或运行 task.py start。

不可妥协的证据规则

如果可以通过探索代码库回答某个问题，就应先探索代码库。

这是强制要求。向用户提问之前，必须先检查答案是否已存在于代码、测试、配置、文档、现有规范或任务历史中。

不要要求用户确认代码库本身可以回答的事实。只询问产品意图、偏好、范围、风险承受度、验收行为，或检查后仍不明确的决策。

代码库证据能够确立当前行为和技术约束。用户期望的行为、功能范围边界和 UX 偏好则无法仅凭代码库证据确定，即使代码库中已有现成模式也是如此；现有模式只是可选方案和建议依据，并非决策。

---

在第 1 阶段规划期间，使用此技能将用户请求转化为清晰的需求和规划文档。

前提条件

只有在用户同意创建任务并准备进入 Trellis 规划阶段后，才能使用此技能。

如果尚无任务，请创建一个：

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --description "<one-line summary>" --slug <slug>)

使用简洁的标题概括用户请求。标题和 --description 都不能为空——create 会拒绝空值，归档时也会拒绝其中任一项为空的记录。使用不带日期前缀的 slug。task.py create 会自动添加 MM-DD- 目录前缀。

task.py create 会创建默认的 prd.md。提出后续问题之前，应根据当前理解更新该文件。

规划流程

1. 在 prd.md 中记录用户请求和已知的初始事实。
2. 提问之前，先检查可用证据：
   • 代码、测试、测试夹具和配置
   • README 文件、文档、现有规范和领域说明
   • 相关的 Trellis 任务、研究文件和会话历史（如有）
3. 将发现的内容划分为：
   • 已确认的事实
   • 仍需用户明确的产品意图
   • 仍需用户决定的范围或风险事项
   • 可能不在范围内的事项
4. 如果仍有一项由用户决定的事项尚未解决，提出价值最高的那个问题，说明你的建议及其权衡，然后停止。本轮不得进行任何实现工作。
5. 用户每次回复后，更新 prd.md，重新整理待决事项，并从第 2 步开始重复流程。
6. 当不再有需要用户决定的事项时，为复杂任务创建或更新 design.md 和 implement.md。
7. 运行需求收敛关卡，然后进行 PRD 收敛审查。
8. 提交最终规划摘要并停止。本轮不得运行 task.py start 或编辑产品代码。
9. 只有在后续用户消息明确批准最新规划摘要后，才能运行 task.py start 并开始实现。如果批准后文档有重大变更，必须重新进行最终审查。

不要臆造项目专属的产品／领域／规范层级。如果代码库已有产品、领域或规范文档，就使用这些文档；如果没有，则依据现有证据继续。

问题规则

每条消息只问一个问题。

每个问题必须包含：

• 需要做出的决定
• 答案为何重要
• 你的推荐答案
• 用户选择其他答案时需要权衡的因素

不要询问是否要搜索、检查文件或继续头脑风暴等流程问题。直接开展证据调查。只有在剩余问题涉及产品决策、偏好、范围边界或风险容忍度时，才向用户提问。

推荐方案不是默认选项。即使用户要求实施，也绝不能擅自替用户选择推荐的产品决策。

如果请求和代码库证据已经解决所有决策，不要凭空制造澄清问题。此时直接进入最终计划摘要；但仍需在之后获得明确批准。

最终审查是必需的阶段转换关卡，不是禁止提出的流程问题。创建任务的同意、最初的实施请求，以及在最近一次最终摘要之前给出的批准，均不满足此关卡要求。

思维框架：第一性原理分析

当需求含糊不清、解决方案显得过度设计，或你正准备“因为大家都这么做”而增加复杂性时，请先将问题分解为基本事实，再据此推导。

步骤 1：重述问题

去除实现细节，用一句话概括问题。

不佳：“我们需要为用户个人资料端点添加 Redis 缓存。” 良好：“用户个人资料加载时间过长。”

步骤 2：列出基本事实

哪些是绝对成立的事实（而非观点或惯例）？

类别	示例
物理限制	网络延迟 ≥ 0，磁盘 I/O 有上限
业务规则	“用户必须只能查看自己的数据”
技术不变量	“数据必须保持一致”
用户需求	“用户希望在 Y 秒内获得 X”

步骤 3：质疑假设

针对当前计划中的每个组成部分：

• 事实还是惯例？“我们一直使用 REST”——为什么？
• **如果去掉它会怎样？**如果没有任何问题，那它就是多余的。
• **是在解决实际问题还是表面症状？**追溯因果链。
• **谁会从这种复杂性中受益？**如果答案是“没人”，就简化。

步骤 4：从事实出发逐步构建

1. 从满足所有事实的最小可行机制开始
2. 只有在某项具体事实要求时，才增加复杂性
3. 每项新增内容都必须回答：“哪项事实要求这样做？”

步骤 5：验证

• 解决方案是否解决了最初的问题？
• 哪些假设需要验证？
• 测试该方案最简单的实验是什么？

需求收敛关卡

最终审查之前，请确认以下各项均已满足：

• 用户预期结果和产品价值明确
• 范围内和范围外的行为明确
• 验收标准描述了可观察的结果
• 用户拥有的产品、范围、UX、兼容性和风险决策均已解决
• 没有尚未解决的阻塞问题
• 技术未知项已完成研究，或已明确延期且不会改变 MVP 行为

轻量级任务可以省略 design.md 和 implement.md；但不能跳过证据检查、需求收敛、最终审查或新的实施批准。

最终计划摘要必须列出目标、范围内事项、范围外事项、验收标准、关键决策、相关风险或延期事项，以及产物状态。

工件规则

prd.md 记录需求和验收内容：

• 目标和用户价值
• 已确认的事实
• 需求
• 验收标准
• 不在范围内的内容
• 仍会阻碍规划的未决问题

design.md 记录复杂任务的技术设计：

• 架构和边界
• 数据流和契约
• 兼容性和迁移说明
• 重要的权衡
• 运行或回滚注意事项

implement.md 记录复杂任务的执行计划：

• 按顺序排列的实施检查清单
• 验证命令
• 高风险文件或回滚节点
• 在 task.py start 前需要进行的后续检查

轻量任务可以只有 prd.md。复杂任务必须在 task.py start 前准备好 prd.md、design.md 和 implement.md。

implement.md 不能替代 implement.jsonl。在子 Agent 派发工作流中，implement.jsonl 和 check.jsonl 必须各自在 task.py start 前至少包含一条真实的规范/研究条目；空清单或仅包含旧版 _example 占位行的清单均不符合要求。内联工作流跳过此 JSONL 门槛，因为 Phase 2 通过 trellis-before-dev 加载上下文。

PRD 收敛审查

在宣布规划就绪或运行 task.py start 之前，按照上述工件规则中描述的最终结构重写一次 prd.md。这不是可有可无的清理工作，而是规划的最终门槛。

此审查必须做到无损：

• 将重复事实合并到一个权威章节中。
• 将 What I already know、Assumptions 和已解决的 Open Questions 等临时头脑风暴章节，整合到目标、背景、需求、技术说明或验收标准中。
• 删除已解决的未决问题，不要留下空章节或已得到解答的章节。
• 如果并行的缺陷列表和需求列表描述的是同一项工作，则将其合并；在对应需求中保留每项缺陷的严重程度、证据和文件:行号锚点。
• 保留每个文件:行号锚点、决策、约束、需求 ID 和验收标准映射。
• 仍有任何阻塞性未决问题时，不要进入最终审查。

审查后，从头到尾通读 prd.md，确认各章节没有重复事实，除非重复内容能提供新信息。

质量标准

宣布规划就绪前：

• prd.md 包含可测试的验收标准。
• prd.md 已通过 PRD 收敛审查：没有尚未处理的临时头脑风暴章节、章节间没有重复事实，也没有丢失锚点、决策或验收映射。
• 已通过检查回答了可从仓库中找到答案的问题。
• 阻塞性未决问题为空。
• 复杂任务已准备好 design.md 和 implement.md。
• 子 Agent 派发任务的 implement.jsonl 和 check.jsonl 中都有经过整理的真实条目；仅含种子条目的清单尚未就绪。
• 已向用户展示最新的最终规划摘要。
• 在后续消息中，用户明确批准了该摘要，以便开始实施。

不要仅仅因为用户最初要求实施就开始实施。