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](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 项：核心思