brainstorm

头脑风暴 - 需求发现（AI 编码增强）

在实现之前，引导 AI 协作发现需求，针对 AI 编码工作流进行优化：

• 任务优先（立即记录想法）
• 先行动，再提问（减少低价值问题）
• 技术选择先调研（避免让用户凭空设想选项）
• 发散 → 收敛（拓展思路，然后确定 MVP）

---

适用场景

当用户描述开发任务时，从 $start 触发，尤其是遇到以下情况：

• 需求不明确或不断变化
• 有多种可行的实现路径
• 权衡取舍很重要（用户体验、可靠性、可维护性、成本、性能）
• 用户可能一开始并不了解最佳选项

---

核心原则（不可妥协）

1. 任务优先（尽早记录） 始终确保一开始就有任务，以便立即记录用户的想法。

2. 先行动，再提问 如果能从代码仓库中的代码、文档、配置、惯例或快速调研中推导出答案，就先这样做。

3. 每条消息只问一个问题 绝不要用一连串问题让用户应接不暇。问一个问题，更新 PRD，然后重复。

4. 优先提供具体选项 对于偏好或决策类问题，提供 2–3 种可行、具体的方案，并说明权衡取舍。

5. 技术选择先调研 如果决策取决于行业惯例、类似工具或成熟模式，就先调研，再提出选项。

6. 发散 → 收敛 初步了解情况后，主动考虑未来演进、相关场景以及失败和边缘情况，然后收敛到 MVP，并明确说明不在范围内的内容。

7. 不问元问题 不要问“要我搜索吗？”或“你能粘贴代码让我继续吗？” 如果需要信息：搜索或检查。如果遇到阻碍：提出最少的阻碍性问题。

---

步骤 0：确保任务存在（始终执行）

开始任何问答之前，确保任务已经存在。如果不存在，就立即创建。

• 根据用户的消息拟定一个临时工作标题。
• 标题不够完美也没关系——稍后在 PRD 中完善。

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)

立即创建/初始化 prd.md，写入已知信息：

# brainstorm: <short goal>

## Goal

<one paragraph: what + why>

## What I already know

* <facts from user message>
* <facts discovered from repo/docs>

## Assumptions (temporary)

* <assumptions to validate>

## Open Questions

* <ONLY Blocking / Preference questions; keep list short>

## Requirements (evolving)

* <start with what is known>

## Acceptance Criteria (evolving)

* [ ] <testable criterion>

## Definition of Done (team quality bar)

* Tests added/updated (unit/integration where appropriate)
* Lint / typecheck / CI green
* Docs/notes updated if behavior changes
* Rollout/rollback considered if risky

## Out of Scope (explicit)

* <what we will not do in this task>

## Technical Notes

* <files inspected, constraints, links, references>
* <research notes summary if applicable>

---

步骤 1：自动收集上下文（提问之前先完成）

在询问“代码是什么样的？”之类的问题之前，先自行收集上下文：

代码仓库检查清单

• 确定可能受影响的模块/文件
• 查找现有模式（类似功能、惯例、错误处理风格）
• 检查配置、脚本和现有命令定义
• 记录任何约束（运行时、依赖策略、构建工具）

文档检查清单

• 查找现有 PRD/规格说明/模板
• 查找命令用法示例、README 和 ADR（如果有）

将发现写入 PRD：

• 添加到 What I already know
• 将约束/链接添加到 Technical Notes

---

步骤 2：分类复杂度（仍有帮助，但不影响创建任务）

复杂度	判定标准	操作
琐碎	单行修复、错别字、明显的改动	跳过头脑风暴，直接实现
简单	目标明确、涉及 1–2 个文件、范围清晰	提出 1 个确认问题，然后实现
中等	涉及多个文件、存在一定歧义	简要头脑风暴（提出 2–3 个高价值问题）
复杂	目标模糊、涉及架构选择、存在多种方案	完整头脑风暴

注意：步骤 0 已经创建了任务。分类只影响头脑风暴的深度。

---

步骤 3：提问门槛（只问高价值问题）

提出任何问题之前，都要执行以下检查：

Gate A — 我能在不询问用户的情况下推导出答案吗？

如果可以通过以下方式获得答案：

• 检查仓库（代码/配置）
• 查阅文档/规范/惯例
• 快速调研市场/开源项目

→ 不要提问。 获取信息、总结并更新 PRD。

Gate B — 这是元问题/偷懒问题吗？

示例：

• “我应该搜索吗？”
• “你能把代码贴出来让我继续吗？”
• “代码是什么样的？”（当仓库可用时）

→ 不要提问。 采取行动。

Gate C — 这属于哪类问题？

• 阻塞性问题：没有用户输入就无法继续
• 偏好问题：存在多种有效选择，取决于产品/UX/风险偏好
• 可推导问题：应该通过检查/调研来回答

→ 只询问阻塞性问题或偏好问题。

---

第 4 步：优先调研模式（技术选型必须采用）

触发条件（满足任意一项 → 优先调研）

• 任务涉及选择方案、库、协议、框架、模板系统、插件机制或 CLI UX 惯例
• 用户询问“最佳实践”“其他人怎么做”“推荐方案”
• 用户无法合理列举选项

调研步骤

1. 找出 2–4 个可比较的工具/模式
2. 总结常见惯例及其存在原因
3. 将这些惯例与我们的仓库约束对应起来
4. 为我们的项目提出 2–3 个可行方案

调研输出格式（PRD）

在 PRD 中添加一个章节（放在 Technical Notes 中或单独成章）：

## Research Notes

### What similar tools do

* ...
* ...

### Constraints from our repo/project

* ...

### Feasible approaches here

**Approach A: <name>** (Recommended)

* How it works:
* Pros:
* Cons:

**Approach B: <name>**

* How it works:
* Pros:
* Cons:

**Approach C: <name>** (optional)

* ...

然后提出一个偏好问题：

• “你更倾向于哪种方案：A / B / C（或其他）？”

---

第 5 步：扩展扫描（DIVERGE）——初步理解后必须执行

能够概述目标后，在收敛思路之前，主动拓展思考。

扩展类别（每类保留 1–2 个项目）

1. 未来演进

   • 1–3 个月后，这个功能可能发展成什么样？
   • 现在有哪些扩展点值得保留？

2. 相关场景

   • 哪些相邻命令/流程应与此保持一致？
   • 是否有对等性预期（创建与更新、导入与导出等）？

3. 失败与边界情况

   • 冲突、离线/网络故障、重试、幂等性、兼容性、回滚
   • 输入验证、安全边界、权限检查

面向用户的扩展消息模板

I understand you want to implement: <current goal>.

Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):

1. Future evolution: <1–2 bullets>
2. Related scenarios: <1–2 bullets>
3. Failure/edge cases: <1–2 bullets>

For this MVP, which would you like to include (or none)?

1. Current requirement only (minimal viable)
2. Add <X> (reserve for future extension)
3. Add <Y> (improve robustness/consistency)
4. Other: describe your preference

然后更新 PRD：

• MVP 包含的内容 → Requirements
• 不包含的内容 → Out of Scope

---

第 6 步：问答循环（CONVERGE）

规则

• 每条消息只问一个问题

• 尽可能优先采用选择题

• 用户每次回答后：

  • 立即更新 PRD
  • 将已回答事项从 Open Questions 移至 Requirements
  • 使用可测试的复选框更新 Acceptance Criteria
  • 明确 Out of Scope

问题优先级（建议）

1. MVP 范围边界（包含/排除哪些内容）
2. 偏好决策（提供具体选项后再询问）
3. 失败/边界行为（仅限 MVP 关键路径）
4. 成功指标与 Acceptance Criteria（如何证明它有效）

建议的问题格式（选择题）

For <topic>, which approach do you prefer?

1. **Option A** — <what it means + trade-off>
2. **Option B** — <what it means + trade-off>
3. **Option C** — <what it means + trade-off>
4. **Other** — describe your preference

---

第 7 步：提出方案并记录决策（复杂任务）

需求足够明确后，提出 2–3 个方案（如果尚未通过优先调研完成）：

Based on current information, here are 2–3 feasible approaches:

**Approach A: <name>** (Recommended)

* How:
* Pros:
* Cons:

**Approach B: <name>**

* How:
* Pros:
* Cons:

Which direction do you prefer?

将结果以 ADR-lite 章节的形式记录在 PRD 中：

## Decision (ADR-lite)

**Context**: Why this decision was needed
**Decision**: Which approach was chosen
**Consequences**: Trade-offs, risks, potential future improvements

---

第 8 步：最终确认与实施计划

解决所有未决问题后，使用结构化摘要确认完整需求：

最终确认格式

Here's my understanding of the complete requirements:

**Goal**: <one sentence>

**Requirements**:

* ...
* ...

**Acceptance Criteria**:

* [ ] ...
* [ ] ...

**Definition of Done**:

* ...

**Out of Scope**:

* ...

**Technical Approach**:
<brief summary + key decisions>

**Implementation Plan (small PRs)**:

* PR1: <scaffolding + tests + minimal plumbing>
* PR2: <core behavior>
* PR3: <edge cases + docs + cleanup>

Does this look correct? If yes, I'll proceed with implementation.

子任务拆分（复杂任务）

对于包含多个独立工作项的复杂任务，创建子任务：

# Create child tasks
CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")

# Or link existing tasks
python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"

---

PRD 目标结构（最终版）

prd.md 应收敛为：

# <Task Title>

## Goal

<why + what>

## Requirements

* ...

## Acceptance Criteria

* [ ] ...

## Definition of Done

* ...

## Technical Approach

<key design + decisions>

## Decision (ADR-lite)

Context / Decision / Consequences

## Out of Scope

* ...

## Technical Notes

<constraints, references, files, research notes>

---

反模式（严格避免）

• 向用户索要可从仓库推导出的代码/上下文
• 尚未提供具体选项就让用户选择方案
• 询问是否需要调研之类的元问题
• 只关注最初的请求，而不考虑演进/边界情况
• 头脑风暴不断发散，却不更新 PRD

与 Start Workflow 集成

头脑风暴完成后（第 8 步确认通过），流程将继续进入 Task Workflow 的第 2 阶段：实现准备：

Brainstorm
  Step 0: Create task directory + seed PRD
  Step 1–7: Discover requirements, research, converge
  Step 8: Final confirmation → user approves
  ↓
Task Workflow Phase 2 (Prepare for Implementation)
  Code-Spec Depth Check (if applicable)
  → Research codebase (based on confirmed PRD)
  → Configure code-spec context (jsonl files)
  → Activate task
  ↓
Task Workflow Phase 3 (Execute)
  Implement → Check → Complete

任务目录和 PRD 已在头脑风暴过程中创建，因此会完全跳过 Task Workflow 的第 1 阶段。

---

相关命令

命令	使用时机
$start	触发头脑风暴的入口
$finish-work	实现完成后
$update-spec	工作过程中出现新模式时