brainstorming

name	brainstorming
description	在开始实现前，把需求澄清成设计文档。适用于新增功能、修改行为、组件设计、接口设计、流程改造、架构取舍和多方案比较。只要改动跨文件、改行为或涉及多方案取舍，就值得先做设计，无论体量大小；单点直改不必走本 skill。用户说'先想一下''先给方案''先规划一下''先比较两种做法'时优先使用这个 skill。
argument-hint	描述要做的功能、约束、背景或已有想法；可留空

Brainstorming Skill

这个 skill 用于把模糊想法收敛成经用户批准的设计文档，再把下一步明确交给 writing-plans。

这是一个 manual-first 的规划 skill，不是实现 skill。 在这个 skill 中，设计获批前不要写代码、不要生成补丁、不要进入实现。

何时使用

在以下场景优先使用这个 skill：

• 用户想新增功能、调整行为、设计组件、设计接口或改变系统流程
• 用户想先比较几种实现方案，再决定怎么做
• 用户只给了目标和约束，但还没有清晰设计
• 任务涉及多个文件、多个边界，或存在明显取舍
• 任务看起来很小，但仍需要先确认范围、成功标准或边界

不要路由到 brainstorming

以下请求默认不要使用这个 skill：

• 已经有批准过的设计文档，只是要写实施计划
• 直接实现、修 bug、改代码、跑测试或提交补丁
• 代码审查、缺陷分析、交接总结、状态同步
• 单纯解释某段代码、回答事实问题，或查找定义

硬约束

• 设计获批前，不要在本 skill 中写代码、生成补丁或切到实现流程
• 一次只问一个问题；如果需要继续追问，也要等用户回答后再问下一题
• 优先使用单选或多选问题；只有在必须时才使用开放题
• 先看当前项目上下文，再提设计建议；跟随现有模式，不做无关重构
• 如果某个问题用图、界面草图、布局对比或关系图会明显更清楚，只在那个具体问题出现时再提出可视化辅助；不要在开场默认提出
• 只有当前 runtime 确实有可用的浏览器、HTML 或绘图工具时，才承诺可视化辅助；工具不存在时，把原则转成文档里的 Mermaid、ASCII 图或文字结构
• 如果需求跨多个独立子系统，先拆分，再只处理第一个子项目
• 设计文档默认要落盘；路径优先级是：用户指定路径 > 仓库已有约定 > docs/specs/
• 写完设计文档后先做 inline 自检，再让用户审批
• CHECKPOINT A/B 必须要求用户给出明确确认令牌；不要把“看起来可以”“先这样”这类含糊认同当批准
• 这个 skill 的终态是进入 writing-plans，不是直接编码

🔴 CHECKPOINTS

• 🔴 CHECKPOINT A · 方案方向确认：范围与关键边界应在 PHASE 2-4 的前置问题里逐一确认完毕；只有在用户回复 接受：推荐方案、接受：方案 A/B/C 或同等明确确认后，才能进入 PHASE 5 写设计文档
• 🔴 CHECKPOINT B · 文档审批：只有在用户回复 批准：<设计文档路径> 或同等明确批准后，才能进入 PHASE 8 和 writing-plans
• 🛑 STOP · 错误路由：如果请求本质上是实现、修 bug、代码审查，或已有设计后的实施计划，立即停止本 skill，改走对应流程

默认形态：

这一步不该继续用 brainstorming，应切到 writing-plans（或实现 / review 流程）。 你现在要的是把已定需求拆成计划 / 直接编码 / 审查，不需要再做方案比较。

模糊表述不算通过检查点，例如“看起来可以”“先这样”“应该行”“你继续吧”“好的”“继续吧”“都行”。遇到这些表述时，只发一个确认问题，要求用户改用上面的确认令牌。

判定“同等明确”（🔴 CHECKPOINT A 与 B 通用）：必须明确点名所选方案（如“方案 A”“推荐方案”）或批准的具体文档（如“批准刚才那份设计”“就按 docs/specs/xxx 批准”），或使用确认令牌本身（接受：... / 批准：<path>）；只表达整体态度（“看起来可以”“先这样”“应该行”“你继续吧”“好的”“继续吧”“都行”）而未点名的，一律视为模糊。半角冒号与全角冒号等价。

红灯与反例

命中下列已知翻车点时按“信号 → 一线动作”处理。本表是诊断索引——每条只写一线动作并指向详细规则归属，不在此重复正文：

信号	一线动作	详见
请求本质不是设计（bugfix / review / 已有设计只要拆计划）	🛑 STOP，路由到实现 / review / writing-plans	“不要路由”、🛑 STOP
mixed intent（实现 + 设计混合）	不编码、不写补丁，只问路由选择题：A 只做设计 / B 停 brainstorming 进实现	—
直接写文档但方案尚未确认	先给推荐方案 + trade-offs，触发 CHECKPOINT A；草稿标“草稿 / 待审批”	CHECKPOINT A
跨多个独立子系统	先拆分，只继续第一个子项目	PHASE 0、硬约束
相关上下文找不到 / 无现成实现	列 1-3 条工作假设，按最保守假设写边界级设计，风险进未决事项	PHASE 1
含糊话术当 CHECKPOINT 批准	不推进，要求 接受：... / 批准：<path> 令牌	🔴 CHECKPOINTS
可视化工具不可用	降级 Mermaid / ASCII / 文字结构，不伪造已验证视觉方案	硬约束
跨轮矛盾 / 拒绝澄清 / 无声漂移	就地守卫已 co-locate 在执行点，见对应 PHASE	PHASE 2、PHASE 5

其余（为“更干净”重做边界 / scope creep via doc / handoff payload 留字面量 <path> 等）已在硬约束与 references/spec-self-review.md 规定，此处不重复。

PHASE 0: 验证请求

开始前先确认：

• 这次请求确实需要设计，而不是单纯实现或审查
• 用户真正想解决的问题、约束和成功标准是什么
• 当前请求是否过大，是否应该先拆成多个子项目

如果需求明显包含多个独立子系统：

• 先指出拆分必要性
• 帮用户明确子项目边界、依赖关系和优先顺序
• 只对第一个子项目继续完整设计流程

PHASE 1: 探索上下文

先读取最小必要的项目上下文：

• 相关文件、文档、已有接口、命名模式
• 与当前需求直接相关的调用点或测试
• 最近改动中会影响本设计的事实

探索目标不是把项目全部看完，而是回答三个问题：

• 当前系统怎么组织这块能力
• 哪些边界已经存在，应该沿用
• 哪些现实约束会影响设计选择

停止条件：一旦能指出最相关的 owning abstraction、一个邻近调用点或测试、一个会影响方案的现实约束，就停止探索并进入澄清或方案比较；不要为了提高信心继续扩大搜索范围。

PHASE 2: 一次一个问题地澄清

先阅读 references/questioning-rules.md 里的规则，再发澄清问题。

澄清阶段的目标：

• 明确目的：为什么要做这件事
• 明确约束：性能、兼容性、时间、依赖、交互方式、发布边界
• 明确成功标准：什么算完成，什么算超范围

默认形态：

先把这次讨论收敛成设计文档，不进入实现。 （若跨子系统）这次需求可拆成 X / Y / Z；这轮只继续 X。 先确认一个点：首要目标更偏 A / B / C？

两条运行期守卫：

• 跨轮矛盾：用户跨轮次给出矛盾回答（如先选方案 A 又否定 A）→ 显式指出矛盾、引用前述具体选择，只问一个问题确认以哪轮为准；若用户确实改主意，回 PHASE 2-3 重做相关澄清，不假装没矛盾。
• 拒绝澄清：用户主动拒绝（“你决定吧”“都行”“你来定”）→ 点明缺哪个约束最致命，给 1 条最保守假设，只问一个问题确认是否接受；仍不给 → 按保守假设写边界级设计，假设与风险进未决事项。

如果某个问题属于真实视觉判断，例如布局、界面草图、关系图或架构图，比文字更容易判断，就在那个问题出现时单独询问是否启用可视化辅助。UI 主题本身不等于视觉问题；如果只是需求、范围或 trade-off 选择，继续用文字提问。

PHASE 3: 提出 2-3 个方案

在你理解需求后，给出 2-3 个方案：

• 每个方案说明核心思路、主要 trade-offs、适用条件
• 优先给推荐方案，并说清推荐原因
• 用 YAGNI 约束设计，不要添加用户没要的复杂度
• 如果现有代码边界已经足够好，优先复用；不要为了“更漂亮”而重做结构

方案比较时同时检查设计单元是否足够清楚：每个单元都应该能回答“它负责什么、怎么使用、依赖什么”。如果必须读内部实现才能理解一个单元的用途，或改内部实现会牵动消费者，边界还没有设计好。

默认形态（每个方案写 4 项：核心思路 / 优点 / 缺点 / 适用条件）：

方案 A：…… 方案 B：…… 方案 C：…… 推荐方案：…… 先确认一个点：请回复 接受：推荐方案，或改选 接受：方案 A/B/C。

PHASE 4: 分段呈现设计并确认

设计要分段呈现，并在每个重要段落后确认：

• 架构与边界
• 关键组件或模块职责
• 单元接口、使用方式和依赖关系
• 数据流或控制流
• 错误处理与回退策略
• 测试策略

每段内容要和复杂度匹配：

• 简单问题可以是几句话
• 复杂问题可以是更完整的段落

如果用户对某一段提出异议：

• 回到相关问题重新澄清
• 修正设计后再继续下一段
• 每一段收尾只保留一个确认动作，不要顺手开启下一段

🔴 CHECKPOINT A：用户没有用 接受：... 或同等明确表述接受推荐方案、范围和关键边界前，不要进入 PHASE 5。

PHASE 5: 写设计文档

在 CHECKPOINT A 通过（用户用 接受：推荐方案 或 接受：方案 A/B/C 等明确令牌接受了所选方案）后，把设计写成文档。

无声漂移守卫：写文档时若偏离了 CHECKPOINT A 已批准的方案（范围、边界或关键取舍），把偏离点单独列出，回到用户面前重新触发 CHECKPOINT A 确认方向；未重确认前按已批准版本写，偏离写进未决事项。

路径选择顺序：

1. 用户显式指定路径
2. 仓库已有设计文档约定
3. 默认写到 docs/specs/<YYYY-MM-DD>-<topic>-design.md

如需固定骨架，先读取 references/spec-template.md。

设计文档至少覆盖：

• 背景与目标
• 范围与非范围
• 方案比较与推荐方案
• 关键边界、组件和职责
• 数据流或控制流
• 错误处理
• 测试策略
• 未决事项

PHASE 6: Inline 自检

写完文档后，读取 references/spec-self-review.md 并完成单轮 inline 自检。

修复真正会影响后续计划的问题：

• TODO、TBD、占位符
• 内部矛盾
• 范围过大
• 含糊到会导致写错计划的要求
• 单元边界、接口或依赖关系含糊到实现者必须猜
• 明显过度设计

不要为了文风润色反复循环。修完就继续。

PHASE 7: 用户审批

自检通过后，明确让用户审阅设计文档。

建议使用类似表述：

设计文档已写好并保存到 <path>。请先审阅这份设计；如果需要改动，我会先改设计，再进入实施计划。 如果批准，请回复 批准：<path>。

如果用户要求修改：

• 修改文档
• 重新跑同一轮 inline 自检
• 再次请求审批

只有在用户明确批准后，才能进入下一阶段。

🔴 CHECKPOINT B：没有 批准：<path> 或同等明确批准，就停在设计阶段；不要切到 writing-plans。

PHASE 8: 过渡到 writing-plans

用户批准设计后：

• 明确说明下一步是 writing-plans
• 把已批准的设计文档路径作为稳定输入
• 输出下面的 handoff payload，供 writing-plans 直接接续：

handoff_to: writing-plans
approved_design: <path>
approval: <用户批准原文>
scope: <本次做什么>
non_scope: <本次不做什么>
open_items: <不阻塞计划的未决事项；没有则写 none>
planning_goal: 基于已批准设计拆成可执行实施计划，不重新做方案比较

• payload 里的 <path> 等尖括号占位符必须替换成真实已批准路径，不要保留字面量
• 不要在本 skill 中直接转入实现
• 如果用户只批准了方向，没有批准文档，回到 PHASE 5-7，不要跳过审批
• 错误路由（请求本质是实施 / 已有批准设计只要拆计划）已在 PHASE 0 与 🛑 STOP 处理；PHASE 8 默认只做交付，不重复路由

关键原则

One question · Multiple choice · YAGNI · Alternatives first · Incremental validation · Just-in-time visual · Isolation & clarity · Follow the repo（各词已在对应 PHASE 与硬约束里定义）

立即执行

先验证请求与范围，再读取最小必要上下文，然后按上述流程推进到已批准的设计文档。