Back to Details

brainstorm

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Brainstorm - Requirements Discovery (AI Coding Enhanced)

头脑风暴 - 需求探索（AI编码增强版）

Guide AI through collaborative requirements discovery before implementation, optimized for AI coding workflows:
  • Task-first (capture ideas immediately)
  • Action-before-asking (reduce low-value questions)
  • Research-first for technical choices (avoid asking users to invent options)
  • Diverge → Converge (expand thinking, then lock MVP)
指导AI在开发实施前完成协作式需求探索，专为AI编码工作流优化：
  • 任务优先（立即捕捉想法）
  • 先行动再询问（减少低价值问题）
  • 技术选型先调研（避免让用户凭空设想方案）
  • 发散→收敛（拓展思路，然后锁定MVP）

When to Use

适用场景

Triggered from 
/trellis:start
when the user describes a development task, especially when:
  • requirements are unclear or evolving
  • there are multiple valid implementation paths
  • trade-offs matter (UX, reliability, maintainability, cost, performance)
  • the user might not know the best options up front
当用户通过
/trellis:start
描述开发任务时触发，尤其适用于以下情况：
  • 需求模糊或不断演变
  • 存在多种可行的实现路径
  • 需要权衡取舍（用户体验、可靠性、可维护性、成本、性能）
  • 用户可能无法提前知晓最佳方案

Core Principles (Non-negotiable)

核心原则（不可妥协）

  1. Task-first (capture early) Always ensure a task exists at the start so the user's ideas are recorded immediately.
  2. Action before asking If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
  3. One question per message Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
  4. Prefer concrete options For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs.
  5. Research-first for technical choices If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
  6. Diverge → Converge After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope.
  7. No meta questions Do not ask "should I search?" or "can you paste the code so I can continue?" If you need information: search/inspect. If blocked: ask the minimal blocking question.
  1. 任务优先（尽早捕捉） 始终确保任务在开始时就已存在，以便立即记录用户的想法。
  2. 先行动再询问 如果可以通过仓库代码、文档、配置、约定或快速调研得到答案——先自行完成这些操作。
  3. 一次只提一个问题 切勿用一连串问题困扰用户。每次提一个问题，更新PRD，重复此流程。
  4. 优先提供具体选项 对于偏好/决策类问题，提供2-3个可行的具体方案，并说明各自的权衡点。
  5. 技术选型先调研 如果决策依赖行业惯例/同类工具/成熟模式，先开展调研，再提出方案。
  6. 发散→收敛 在初步理解需求后，主动考虑未来演进、相关场景以及故障/边缘情况——然后收敛到明确排除非核心内容的MVP。
  7. 不提元问题 不要问“我应该搜索吗？”或“你能粘贴代码让我继续吗？”这类问题。 如果需要信息：自行搜索/检查。如果遇到阻塞：只提最关键的阻塞问题。

Step 0: Ensure Task Exists (ALWAYS)

步骤0：确保任务存在（必须执行）

Before any Q&A, ensure a task exists. If none exists, create one immediately.
  • Use a temporary working title derived from the user's message.
  • It's OK if the title is imperfect — refine later in PRD.
bash
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
Create/seed 
prd.md
immediately with what you know:
markdown
undefined
在任何问答之前，确保任务已存在。如果不存在，立即创建。
  • 使用从用户消息中提炼的临时工作标题。
  • 标题不完善也没关系——后续在PRD中优化。
bash
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
立即创建/初始化
prd.md
文件，填入已知信息：
markdown
undefined

brainstorm: <short goal>

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
  • 添加/更新测试（适当时添加单元/集成测试）
  • Lint/类型检查/CI全部通过
  • 如果行为有变更，更新文档/说明
  • 如果存在风险，考虑发布/回滚方案

Out of Scope (explicit)

非核心范围（明确列出）

  • <what we will not do in this task>
  • <本任务中不会执行的内容>

Technical Notes

技术说明

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

---
  • <检查过的文件、约束条件、链接、参考资料>
  • <如有必要，添加调研笔记摘要>

---

Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS)

步骤1：自动获取上下文（提问前必须执行）

Before asking questions like "what does the code look like?", gather context yourself:
在问“代码是什么样的？”这类问题之前，先自行收集上下文：

Repo inspection checklist

仓库检查清单

  • Identify likely modules/files impacted
  • Locate existing patterns (similar features, conventions, error handling style)
  • Check configs, scripts, existing command definitions
  • Note any constraints (runtime, dependency policy, build tooling)
  • 确定可能受影响的模块/文件
  • 查找现有模式（类似功能、约定、错误处理风格）
  • 检查配置、脚本、现有命令定义
  • 记录任何约束条件（运行时、依赖策略、构建工具）

Documentation checklist

文档检查清单

  • Look for existing PRDs/specs/templates
  • Look for command usage examples, README, ADRs if any
Write findings into PRD:
  • Add to 
    What I already know
  • Add constraints/links to 
    Technical Notes
  • 查找现有PRD/规格/模板
  • 查找命令使用示例、README、ADR（如果有）
将发现的内容写入PRD：
  • 添加到“已知信息”部分
  • 将约束条件/链接添加到“技术说明”部分

Step 2: Classify Complexity (still useful, not gating task creation)

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

ComplexityCriteriaAction
TrivialSingle-line fix, typo, obvious changeSkip brainstorm, implement directly
SimpleClear goal, 1–2 files, scope well-definedAsk 1 confirm question, then implement
ModerateMultiple files, some ambiguityLight brainstorm (2–3 high-value questions)
ComplexVague goal, architectural choices, multiple approachesFull brainstorm
Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
复杂度判断标准行动方案
Trivial单行修复、拼写错误、明显的变更跳过头脑风暴，直接实现
简单目标明确，涉及1-2个文件，范围清晰提1个确认问题，然后实现
中等涉及多个文件，存在部分模糊点轻度头脑风暴（2-3个高价值问题）
复杂目标模糊，涉及架构选择，存在多种实现路径完整头脑风暴
注意：任务已在步骤0中创建。分类仅影响头脑风暴的深度。

Step 3: Question Gate (Ask ONLY high-value questions)

步骤3：问题审核（仅提出高价值问题）

Before asking ANY question, run the following gate:
在提出任何问题之前，先通过以下审核：

Gate A — Can I derive this without the user?

审核A — 无需用户即可自行获取答案？

If answer is available via:
  • repo inspection (code/config)
  • docs/specs/conventions
  • quick market/OSS research
→ Do not ask. Fetch it, summarize, update PRD.
如果答案可通过以下途径获取：
  • 仓库检查（代码/配置）
  • 文档/规格/约定
  • 快速市场/开源软件调研
→ 不要提问。自行获取信息，总结后更新PRD。

Gate B — Is this a meta/lazy question?

审核B — 这是元问题/懒惰问题吗？

Examples:
  • "Should I search?"
  • "Can you paste the code so I can proceed?"
  • "What does the code look like?" (when repo is available)
→ Do not ask. Take action.
示例：
  • “我应该搜索吗？”
  • “你能粘贴代码让我继续吗？”
  • “代码是什么样的？”（当仓库可访问时）
→ 不要提问。直接采取行动。

Gate C — What type of question is it?

审核C — 问题类型是什么？

  • Blocking: cannot proceed without user input
  • Preference: multiple valid choices, depends on product/UX/risk preference
  • Derivable: should be answered by inspection/research
→ Only ask Blocking or Preference.
  • 阻塞性：没有用户输入无法继续
  • 偏好类：存在多个有效选择，取决于产品/用户体验/风险偏好
  • 可推导：应通过检查/调研得到答案
→ 仅提出阻塞性或偏好类问题。

Step 4: Research-first Mode (Mandatory for technical choices)

步骤4：先调研模式（技术选型时强制使用）

Trigger conditions (any → research-first)

触发条件（满足任一即启用先调研模式）

  • The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention
  • The user asks for "best practice", "how others do it", "recommendation"
  • The user can't reasonably enumerate options
  • 任务涉及选择实现方案、库、协议、框架、模板系统、插件机制或CLI用户体验约定
  • 用户询问“最佳实践”、“其他工具如何实现”、“推荐方案”
  • 用户无法合理列举所有选项

Research steps

调研步骤

  1. Identify 2–4 comparable tools/patterns
  2. Summarize common conventions and why they exist
  3. Map conventions onto our repo constraints
  4. Produce 2–3 feasible approaches for our project
  1. 确定2-4个可对比的工具/模式
  2. 总结常见惯例及其存在的原因
  3. 将这些惯例映射到我们仓库的约束条件中
  4. 为我们的项目生成2-3个可行方案

Research output format (PRD)

调研输出格式（写入PRD）

Add a section in PRD (either within Technical Notes or as its own):
markdown
undefined
在PRD中添加一个章节（可放在“技术说明”内或单独作为章节）：
markdown
undefined

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)
  • ...

Then ask **one** preference question:

* "Which approach do you prefer: A / B / C (or other)?"

---
方案A：<名称>（推荐）
  • 实现方式：
  • 优点：
  • 缺点：
方案B：<名称>
  • 实现方式：
  • 优点：
  • 缺点：
方案C：<名称>（可选）
  • ...

然后提出**一个**偏好类问题：

* “你偏好哪种方案：A / B / C（或其他）？”

---

Step 5: Expansion Sweep (DIVERGE) — Required after initial understanding

步骤5：拓展扫描（发散）—— 初步理解后必须执行

After you can summarize the goal, proactively broaden thinking before converging.
在能够总结目标之后，在收敛之前主动拓展思路。

Expansion categories (keep to 1–2 bullets each)

拓展类别（每个类别保留1-2个要点）

  1. Future evolution
    • What might this feature become in 1–3 months?
    • What extension points are worth preserving now?
  2. Related scenarios
    • What adjacent commands/flows should remain consistent with this?
    • Are there parity expectations (create vs update, import vs export, etc.)?
  3. Failure & edge cases
    • Conflicts, offline/network failure, retries, idempotency, compatibility, rollback
    • Input validation, security boundaries, permission checks
  1. 未来演进
    • 该功能在1-3个月后可能会变成什么样？
    • 现在值得保留哪些扩展点？
  2. 相关场景
    • 哪些关联命令/流程需要与此保持一致？
    • 是否存在对等性要求（创建 vs 更新，导入 vs 导出等）？
  3. 故障与边缘情况
    • 冲突、离线/网络故障、重试、幂等性、兼容性、回滚
    • 输入验证、安全边界、权限检查

Expansion message template (to user)

拓展消息模板（发给用户）

markdown
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
Then update PRD:
  • What's in MVP → 
    Requirements
  • What's excluded → 
    Out of Scope
markdown
我理解你想要实现：<当前目标>。

在深入设计之前，我先快速从三个维度拓展思路（避免后续返工）：

1. 未来演进：<1-2个要点>
2. 相关场景：<1-2个要点>
3. 故障/边缘情况：<1-2个要点>

对于本次MVP，你希望包含哪些内容（或都不包含）？

1. 仅实现当前需求（最小可行版本）
2. 添加<X>（为未来扩展预留空间）
3. 添加<Y>（提升健壮性/一致性）
4. 其他：描述你的偏好
然后更新PRD：
  • MVP包含的内容 → “需求”部分
  • 排除的内容 → “非核心范围”部分

Step 6: Q&A Loop (CONVERGE)

步骤6：问答循环（收敛）

Rules

规则

  • One question per message
  • Prefer multiple-choice when possible
  • After each user answer:
    • Update PRD immediately
    • Move answered items from 
      Open Questions
      → 
      Requirements
    • Update 
      Acceptance Criteria
      with testable checkboxes
    • Clarify 
      Out of Scope
  • 一次只提一个问题
  • 尽可能使用选择题形式
  • 在每次收到用户回答后：
    • 立即更新PRD
    • 将已回答的问题从“待解决问题”移至“需求”
    • 用可测试的复选框更新“验收标准”
    • 明确“非核心范围”

Question priority (recommended)

问题优先级（推荐）

  1. MVP scope boundary (what is included/excluded)
  2. Preference decisions (after presenting concrete options)
  3. Failure/edge behavior (only for MVP-critical paths)
  4. Success metrics & Acceptance Criteria (what proves it works)
  1. MVP范围边界（包含/排除的内容）
  2. 偏好决策（在提供具体选项之后）
  3. 故障/边缘行为（仅针对MVP关键路径）
  4. 成功指标与验收标准（如何证明功能有效）

Preferred question format (multiple choice)

推荐问题格式（选择题）

markdown
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
markdown
关于<主题>，你偏好哪种方案？

1. **选项A** — <说明内容 + 权衡点>
2. **选项B** — <说明内容 + 权衡点>
3. **选项C** — <说明内容 + 权衡点>
4. **其他** — 描述你的偏好

Step 7: Propose Approaches + Record Decisions (Complex tasks)

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

After requirements are clear enough, propose 2–3 approaches (if not already done via research-first):
markdown
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?
Record the outcome in PRD as an ADR-lite section:
markdown
undefined
当需求足够清晰后，提出2-3个方案（如果尚未通过先调研模式完成）：
markdown
基于当前信息，以下是2-3个可行方案：

**方案A：<名称>**（推荐）

* 实现方式：
* 优点：
* 缺点：

**方案B：<名称>**

* 实现方式：
* 优点：
* 缺点：

你偏好哪个方向？
在PRD中添加一个轻量ADR章节记录结果：
markdown
undefined

Decision (ADR-lite)

决策（轻量ADR）

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

---
背景：为何需要做出此决策 决策：选择了哪种方案 影响：权衡点、风险、未来潜在改进方向

---

Step 8: Final Confirmation + Implementation Plan

步骤8：最终确认 + 实施计划

When open questions are resolved, confirm complete requirements with a structured summary:
当待解决问题全部解决后，用结构化总结确认完整需求：

Final confirmation format

最终确认格式

markdown
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.
markdown
以下是我对完整需求的理解：

**目标**：<一句话总结>

**需求**：

* ...
* ...

**验收标准**：

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

**完成定义**：

* ...

**非核心范围**：

* ...

**技术方案**：
<简要总结 + 关键决策>

**实施计划（拆分小PR）**：

* PR1：<脚手架 + 测试 + 基础 plumbing>
* PR2：<核心功能>
* PR3：<边缘情况 + 文档 + 清理>

这样是否正确？如果确认，我将开始实施。

PRD Target Structure (final)

PRD最终目标结构

prd.md
should converge to:
markdown
undefined
prd.md
最终应收敛为以下结构：
markdown
undefined

<Task Title>

<任务标题>

Goal

目标

<why + what>
<原因 + 内容>

Requirements

需求

  • ...
  • ...

Acceptance Criteria

验收标准

  • ...
  • ...

Definition of Done

完成定义

  • ...
  • ...

Technical Approach

技术方案

<key design + decisions>
<关键设计 + 决策>

Decision (ADR-lite)

决策（轻量ADR）

Context / Decision / Consequences
背景 / 决策 / 影响

Out of Scope

非核心范围

  • ...
  • ...

Technical Notes

技术说明

<constraints, references, files, research notes>

---
<约束条件、参考资料、文件、调研笔记>

---

Anti-Patterns (Hard Avoid)

反模式（严格避免）

  • Asking user for code/context that can be derived from repo
  • Asking user to choose an approach before presenting concrete options
  • Meta questions about whether to research
  • Staying narrowly on the initial request without considering evolution/edges
  • Letting brainstorming drift without updating PRD
  • 向用户索要可从仓库获取的代码/上下文
  • 在提供具体选项之前让用户选择方案
  • 询问是否需要调研这类元问题
  • 仅局限于初始请求，不考虑演进/边缘情况
  • 头脑风暴偏离方向却不更新PRD

Integration with Start Workflow

与启动工作流的集成

High-level flow:
text
User describes task
↓
Step 0: Ensure task exists (create if missing)
↓
Step 1: Auto-context (inspect repo/docs, research if needed)
↓
Step 2: Classify complexity
↓
Step 4 (if triggered): Research-first → propose options
↓
Step 5: Expansion sweep (diverge)
↓
Step 6: Q&A loop (converge; update PRD each turn)
↓
Step 8: Final confirmation + small-PR plan
↓
Implement
高层级流程：
text
用户描述任务
↓
步骤0：确保任务存在（不存在则创建）
↓
步骤1：自动获取上下文（检查仓库/文档，必要时调研）
↓
步骤2：分类复杂度
↓
步骤4（如果触发）：先调研 → 提出方案
↓
步骤5：拓展扫描（发散）
↓
步骤6：问答循环（收敛；每次循环后更新PRD）
↓
步骤8：最终确认 + 小PR计划
↓
实施

Related Commands

相关命令

CommandWhen to Use
/trellis:start
Entry point that triggers brainstorm
/trellis:finish-work
After implementation is complete
/trellis:update-spec
If new patterns emerge during work
命令适用场景
/trellis:start
触发头脑风暴的入口
/trellis:finish-work
实施完成后使用
/trellis:update-spec
如果工作过程中出现新模式时使用