| name | brainstorm |
| description | Use when starting any creative work — creating features, components, or functionality, modifying behavior, or solving ambiguous problems — before design or implementation. Covers product discovery, competitive research, feature analysis, technical design, and capability spec writing. Applies to every project; routes to writing-plans (non-UI) or design-workflow (UI). |
| origin | rune |
Brainstorm
将模糊的产品想法精炼为按 capability 组织的行为契约（docs/specs/<capability>-spec.md）；技术设计产物交 writing-plans（plan）。spec 纯行为，排除实现。
Announce at start: "I'm using the brainstorm skill to explore this idea and produce capability spec(s)."
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until either (a) Phase 5 spec is written and user has approved it, or (b) the **Scale Gate** (see below) has publicly classified the change as Truly Simple and the user has acknowledged. This applies to EVERY project regardless of perceived simplicity.
Anti-Pattern: "This Is Too Simple To Need A Design"
Every project goes through this process. A config change, a single-function utility — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
Scale Gate（在 HARD-GATE 之后立即判定）
启动 brainstorm 时第一动作就是对改动规模做公开判定。匹配 Truly Simple 时走简化路径，绕过 Phase 2/3/4/5/6 但保留质量门与审查闸。
Truly Simple 判定（必须全部满足）
- 单文件改动，且实际变更 ≤30 行
- 无新文件、无新依赖、无新模块、无新数据模型
- 无新行为：不改业务逻辑、不改 API 契约、不改公开接口
- 典型场景：修 typo / 改注释 / 调 hook regex / 调 README / 配置项调整 / skill 措辞调整
任一不满足 → 走完整 6-Phase 流程。
Truly Simple 路径（chore-light）
- 公开判定：在第一条消息中显式公告 "Scale Gate 判定为 Truly Simple：[一句话说明改什么]"
- 用户确认：等用户明确认可（"go"/"ok"/"对"/"动手"等即可）
- 跳过 Phase 2/3/4/5/6 —— 不写 spec 文件、不进入 writing-plans、不进入 subagent-driven-development
- 执行链：edit →
/code-quality-gate → /code-review (per-task 模式，code-quality-reviewer-prompt) → commit（Conventional Commits）
仍不可绕过
- post-edit
/code-quality-gate（format/lint/typecheck/debug 扫描）
/code-review per-task（hook pre-commit-review-check.py 物理强制）- commit 走 Conventional Commits（hook
pre-bash-guard.sh 物理强制）
- 涉及 secrets / 认证 / DB 查询 / 文件系统 / 加密 → 仍触发安全审查（code-quality-reviewer-prompt.md 内置 OWASP Top 10）
用户随时可驳回
用户回应 "走完整 brainstorm" 或 "这不算 chore" → 立即放弃 Truly Simple 判定，回到 Phase 1。
反逃避
- NEVER 自判 Truly Simple 直接 edit 而不公告判定
- NEVER 把"≤30 行"作为唯一标准（行数小但改业务逻辑 = 不是 chore）
- NEVER 把 reviewer/quality-gate 也跳过（这是 L3，不可绕）
- NEVER 把多个 chore 攒一块跑（每个 chore 走自己的简化链）
Abandoned 判定
用户明确表示"不做了"/"取消"/"放弃"时：
-
公告：在消息中显式说明 "Feature [name] 标记为 Abandoned"
-
检查已有产物：相关 capability spec（docs/specs/<capability>-spec.md）或 docs/designs/<feature>/ 是否已存在
-
按产物分支处理：
| 状态 | 处理 |
|---|
| 有产物（spec 或 design 目录任一存在） | 调用 /doc-sync（context=abandoned）追加 abandoned 标记 → 提交 docs commit（见下） |
| 无产物（Phase 1-4 中止，未写入任何文件） | 仅对话确认放弃，不调任何 skill，不写文件，不 commit |
-
有产物时提交 docs commit：
git add docs/
git commit -m "docs(<feature>): mark as abandoned"
brainstorm Abandoned 不经过 finishing，doc-sync 产出由本步骤直接提交（与 finishing Step 2c 同等职责）。
-
用户确认
不走完整的 Scale Gate 或 Phase 流程。
核心原则
PM 的职责是追问和挑战，不是附和。
- 不急着给出答案，先确保问题被正确理解
- 主动识别用户未说出的假设
- 每一步都有明确的完成标准，信息不够不进入下一步
- 输出的文档是下游工作流的输入，格式必须精确对接
Phase Overview
Phase 1: Product Discovery（必经）
│
├─▶ Phase 2: Competitive Research（可选）
│
├─▶ Phase 3: Feature Analysis
│
├─▶ Phase 4: Technical Design（纯 UI 可跳过）
│
├─▶ Phase 5: Spec Writing（Phase 4 完成时必经）
│
└─▶ Phase 6: Routing
Phase 1 — Product Discovery（必经入口）
通过自由式对话，帮用户从一个模糊想法梳理出产品轮廓。
执行方式：
根据用户的 idea 类型，动态选择追问方向。不使用固定问题模板，而是根据对话内容即时追问。
追问维度参考（按需选用，不全问）：
问题空间：
- 这个产品解决什么痛点？现在用户怎么解决？
- 目标用户是谁？有没有具体的用户画像？
- 使用场景是什么？什么时候、在什么情况下会用？
产品形态：
- 是 Web / App / 小程序 / 平台 / 工具？
- 用户第一次打开会看到什么？
- 核心使用流程是怎样的？（1-2 分钟 walk-through）
价值与边界：
- 做成什么样的算成功？什么样的算失败？
- 有什么是明确不做的？
- 跟现有工具/方案相比，独特之处是什么？
追问节奏：
- 每轮对话最多问 2-3 个问题，不要一次抛出所有问题
- 根据用户的回答追问更深，而不是换话题
- 当用户开始重复已说过的内容时，说明信息已经足够
输出（不写文件，在对话中确认）：
## 产品轮廓
**一句话描述**：[产品是什么，给谁，解决什么问题]
**目标用户**：[用户画像]
**产品形态**：[Web / App / 平台 / 工具]
**核心场景**：
1. [场景描述]
2. [场景描述]
**初版功能清单**：
- [功能 1]：[简要描述]
- [功能 2]：[简要描述]
- ...
**明确的边界（不做什么）**：
- ...
完成门槛： 用户确认产品轮廓准确，无重大遗漏。
然后主动提议： 「产品轮廓已明确，是否进入竞品调研？也可以直接跳到功能分析或技术设计。」
Phase 2 — Competitive Research（可选）
通过 web search 找到已有解决方案，列出功能对比。
执行方式：
- 根据产品轮廓提取搜索关键词
- 使用 WebSearch / Context7 搜索竞品和替代方案
- 整理为功能对比表
搜索策略：
第一轮搜索：[产品类型] + "tools" / "platform" / "app" / "alternatives"
第二轮搜索：针对发现的具体竞品，搜索功能评测和用户评价
输出（不写文件，在对话中确认）：
竞品分析
- 竞品对比：列出 2-4 个直接竞品或间接替代方案，按需展开维度（定位 / 核心功能 / 差异化 / 定价）
- 市场空白：1-3 句描述未被满足的需求
- 对我们的启发：1-3 句结论性判断（参考什么、避开什么）
未找到直接竞品时，分析间接替代方案（用户当前用什么方式解决这个问题）。
完成门槛： 用户确认竞品/替代方案合理（找到的竞品列表无遗漏，或空白市场判断成立）。
然后主动提议： 「竞品分析已完成，是否进入功能分析？」
Phase 3 — Feature Analysis
将功能清单进行优先级排序，定义 MVP 范围。
执行方式：
- 回顾 Phase 1 的功能清单 + Phase 2 的竞品启发
- 与用户讨论每个功能的优先级
- 确定哪些是 MVP 必须有的，哪些可以后续迭代
优先级标准：
P0 — MVP 必须：没有这个功能，产品不成立
P1 — 重要但可延后：有了更好，没有也能用
P2 — 锦上添花：时间允许再做
判定依据：
- 这个功能去掉后，核心场景还能跑通吗？→ 不能 = P0
- 竞品都有这个功能吗？且用户会因此流失吗？→ 是 = P1
- 这个功能是"有了更好"还是"必须有"？→ 前者 = P2
输出（不写文件，在对话中确认）：
## 功能分析
**MVP 定义**：
MVP 范围 = P0 功能集合，目标是 [一句话描述 MVP 交付的核心价值]
**功能优先级**：
| 功能 | 优先级 | 理由 | 依赖 |
|------|--------|------|------|
| [功能 1] | P0 | [为什么必须] | 无 |
| [功能 2] | P0 | [为什么必须] | [功能 1] |
| [功能 3] | P1 | [为什么重要] | 无 |
| [功能 4] | P2 | [为什么锦上添花] | [功能 3] |
**功能依赖关系**：
[功能 A] → [功能 B]（B 依赖 A 先完成）
**迭代规划建议**：
- V1 (MVP)：P0 功能
- V2：P1 功能
- V3：P2 功能
完成门槛： 用户确认 MVP 范围合理，优先级无争议。
然后主动提议： 「功能分析已完成，是否进入技术设计？」
Phase 4 — Technical Design
将产品定义转化为技术方案。根据复杂度走 L1 或 L2 路径。
L1 / L2 路由
| 条件 | 级别 | 深度 |
|---|
| 单模块内改动，技术栈不变，无新依赖 | L1（轻量） | 简要方案对比 + 核心设计决策 |
| 跨模块、新依赖、数据模型变更、系统集成 | L2（标准） | 完整方案比选 + 详细设计 |
4a. Codebase Context Gathering
在提出技术方案前，先了解现状：
- 读取现有 ADR（
docs/architecture/adr/*.md），了解已有决策和约束
- 读取 codemap（
docs/CODEMAP.md），了解项目整体结构
- 读 CODEMAP（
docs/CODEMAP.md）了解模块职责与依赖结构；需要具体公共 API 时直接读源码（入口文件列）
- 读取相关产品文档，了解需求上下文
- 扫描相关源码，了解当前实现
4b. Propose 2-3 Technical Approaches
提出至少 2 个技术方案，每个方案包含：
## 方案 A：[名称]
**描述**：[方案描述]
**优点**：
- [...]
**缺点**：
- [...]
**影响范围**：[...]
**实现复杂度**：低/中/高
---
## 方案 B：[名称]
[同上格式]
给出推荐方案和理由。
4c. Present Design in Sections
对推荐方案（或用户选择的方案），分段展示设计。每段确认后再进入下一段。
Scale each section to its complexity：简单的几句话即可，复杂的可到 200-300 字。
覆盖维度：
- Architecture — 整体架构、组件划分、模块交互
- Components — 核心组件职责和接口
- Data Flow — 数据流向、状态管理、持久化策略
- Error Handling — 错误分类、恢复策略、边界情况
- Testing — 测试策略、关键测试场景
4d. User Confirms Approach Selection
展示推荐方案和理由，等待用户明确选择。不自行推进。
用户可以选择推荐方案、其他方案，或要求混合/修改。
完成门槛： 用户明确选择了技术方案。
4e. ADR（条件 — 跨项目级架构决策）
仅当选定方案是跨项目级架构决策时写 ADR；feature-local 决策不写。判据（满足任一即跨项目级，复用 Phase 4 L1/L2 路由信号）：
- 引入新框架 / 新依赖 / 新数据模型
- 跨系统集成 / 跨 ≥2 模块的基础设施变更
- 无现有 ADR 先例的技术选型
命中判据：
- 调 doc-ops skill（write 模式，模板：
adr）写入 docs/architecture/adr/<NNNN>-<slug>.md（编号扫描 docs/architecture/adr/ 取下一个）
- 调 doc-ops skill（sync 模式，scope=Decisions 段）把该 ADR 加入
docs/FEATURE-CATALOG.md 的 Decisions 段（ADR | 标题 | 状态=已批准 | 日期 | 关联 Feature）
未命中判据 → 跳过本步，不写 ADR。
Phase 4 产物去向：技术设计（方案选择、架构、数据模型、API 决策）不进 spec——交给 writing-plans 写入 docs/changes/<feature>/design.md。spec 只收行为契约（见 Phase 5）。
Phase 5 — Capability Spec（行为契约，经 changes/ delta）
把 Phase 1-3 确定的行为表达为 change 的 delta（docs/changes/<feature>/）。只写行为，不写实现——技术设计已在 Phase 4 交 writing-plans（→ changes/<feature>/design.md）；竞品/产品框架/指标是对话级上下文，不入耐久文档。不直接动 docs/specs/——specs/ 的更新由 finishing 把 delta apply 落定。
5a. Capability Mapping
先定位本 feature 触及哪些 capability（决定 delta 段）：
- 读现有 capability 库
docs/specs/*-spec.md + docs/CODEMAP.md，了解已有行为域
- 判断对每个相关 capability 是
new（建新 spec）还是 modify（改现有）
- 输出清单：
[(<capability>, new|modify), ...]
一个 feature 可能触及多个 capability；也可能引入全新 capability。
5b. 写 Change 文件夹（proposal + specs.md delta）
按 5a 清单，调 doc-ops skill（write 模式）写 docs/changes/<feature>/：
- proposal.md（模板
change-proposal）：意图 + 受影响 capabilities 清单（5a 结果）+ 关联 ADR（若有）
- specs.md（模板
change-specs-delta，OpenSpec diff 格式）：按 capability 分段的行为 delta——new capability 全 +（ADD）；modify capability 用 +/- 标增删改的 Requirements/Scenarios。行为来自 Phase 1 核心场景 + Phase 3 功能分析
纪律：delta 只写行为（含错误行为）；不写 Architecture / Data Model / API 结构 / 技术选型（那些进 design.md）。design.md + tasks.md 由 writing-plans 后续补。
写入后：
→ 调 doc-ops skill（sync 模式，scope=Features 段）更新 FEATURE-CATALOG（Features 段：Status=Draft；Spec 列填触及的 capability spec(s)）
寻址锚点：feature 名锚定整个 docs/changes/<feature>/ 文件夹（proposal/specs/design/tasks 同名同居）；capability spec 按 capability 名寻址于 docs/specs/。design-workflow / writing-plans 通过 5a mapping 知道该读哪些 capability spec；finishing 读 specs.md delta apply 到 specs/。
5c. Self-Review + 用户审阅
用 fresh eyes 做四项检查：① Placeholder 扫描（TBD/TODO/模糊需求）；② 内部一致（delta 的 +/- 与 proposal 清单一致、无矛盾）；③ 行为可验证（每个 ADD/MODIFY 的 Scenario 能测）；④ 行为/实现分离（无架构/数据模型等技术内容混入）。发现问题 inline 修复。
然后请用户审阅 changes/<feature>/（proposal + specs.md delta），等待确认后才进入 Phase 6。
Phase 6 — Routing
根据功能性质判断后续工作流路径：
判断依据：
1. 是否涉及 UI？
- 否 → 纯 Development Workflow
- 是 → 继续
2. UI 复杂度如何？
- 小改动（按钮、文案、布局微调）→ L1 轻量设计 → Development Workflow
- 新页面/新组件/新交互 → L2 标准设计流程 (V2-1 到 V2-4) + Development Workflow
输出（在对话中确认）：
## 路由决策
后续工作流：[Design Workflow L2 / Development Workflow / L1 Lightweight Design]
理由：[一句话]
路由决策是建议而非强制，用户可以否决并调整路径。
Phase 间跳转规则
| 从 | 可跳到 | 条件 |
|---|
| Phase 1 | Phase 3 | 跳过竞品直接排优先级 |
| Phase 1 | Phase 4 | 用户已有清晰产品定义，不需要竞品和优先级 |
| Phase 2 | Phase 4 | 跳过优先级直接进入技术设计 |
| Phase 4 | Phase 3 | 技术设计中发现需要重新评估功能范围 |
| 任意 Phase | Phase 6 | 用户说"够清楚了，直接开干" |
不可跳过：
- Phase 1（必须理解问题）
- Phase 5（如果 Phase 4 已完成，必须写 spec）
Pass Criteria
Common Mistakes
错误：附和用户而不是追问
- 用户说"我需要一个 X 功能"时，不急着记录，先问"为什么需要？解决什么问题？"
- 避免"好主意！"式的肯定，用"这个想法有意思，能多说说…"来引导深入
错误：把用户要求当作用户需求
- 用户说"加个搜索"可能是"信息太多了找不到"的问题，搜索不一定是唯一解
- 区分 wants（用户说的）和 needs（用户真正需要的）
错误：过早收敛到具体方案
- Phase 1 的目标是理解问题空间，不是设计解决方案
- 如果用户一开始就描述具体功能，引导回"这个功能解决什么问题"
错误：跳过竞品调研直接定义功能
- 即使是创新产品，了解已有方案能避免重复造轮子
- 竞品的不足是最有价值的产品方向信号
错误：MVP 范围过大
- MVP 应该是"最小可验证"，不是"最小可用产品"
- 如果 MVP 需要超过 5 个 P0 功能，可能还不够聚焦
错误：跳过 spec self-review
- 写完 spec 后必须过一遍 placeholder/consistency/scope/ambiguity 四项检查
- "写完了直接给用户看" 等于跳过了质量门控
错误：不经用户审阅直接进入 planning
- spec 文件必须经过用户审阅并明确批准
- "我写完了，开始做计划吧" 不算用户批准
与现有工作流的衔接
/brainstorm
│
├─ Phase 1-3 + capability mapping → doc-ops write: change-proposal + change-specs-delta
│ → docs/changes/<feature>/{proposal,specs}.md
│ (Phase 4 技术设计 → writing-plans → docs/changes/<feature>/design.md)
│ design-workflow V2-1 / writing-plans 读相关 capability specs
│ finishing 读 changes/<feature>/specs.md → apply 到 docs/specs/
│
└─ 调 doc-ops skill（sync 模式）更新 feature catalog（Spec 列 = 触及的 capability specs）
