@chenguangyao/devflow-kit 0.1.43

package/skills/archive/references/spec-merge.md

@@ -0,0 +1,365 @@
+# archive / spec-merge
+
+delta → spec 合并语义、heading 规则、多 delta 顺序、边界 case。
+
+---
+
+## 总体模型(OpenSpec-inspired)
+
+`devflow/specs/` 代表**当前在生产运行的能力清单**。每个 capability 一个 markdown,描述"系统声明能做什么 + 怎么做"。
+
+`delta/*.md` 是本次 change 对 specs 的**增量改动声明**。archive 把这些 delta 合进 specs,使之保持同步。
+
+---
+
+## 目录结构
+
+```
+devflow/
+├── specs/
+│   ├── coupon-management.md       ← 券管理能力
+│   ├── order-refund.md             ← 退款能力
+│   └── user-notification.md        ← 通知能力
+└── changes/<slug>/delta/
+    ├── coupon-management.md        ← 本 change 对 coupon-management 的改动
+    └── coupon-batch-grant.md       ← 本 change 新增的 capability
+```
+
+delta 文件名 = 目标 spec 文件名。不存在同名 spec → 按"新 capability"处理(整个 delta 作为新 spec 内容)。
+
+---
+
+## 三种 marker
+
+### ADDED
+
+新增一条 requirement。
+
+```markdown
+## ADDED: 批量发放优惠券
+
+### 批量发放优惠券
+
+系统 SHALL 支持单批 ≤ 10000 条的批量发放请求,
+单条处理失败不影响其他条的处理,
+返回结果中包含 grantedCount 和 failedCount。
+
+failedReasons MUST 精确到具体用户和具体原因。
+```
+
+合并动作:在 `specs/coupon-management.md` 的 `## Requirements` section 下追加整个 `### 批量发放优惠券` 块。
+
+### MODIFIED
+
+修改已有 requirement 的描述。
+
+```markdown
+## MODIFIED: 优惠券发放
+
+### 优惠券发放
+
+系统 SHALL 支持单条或批量发放优惠券。
+单条发放 P99 ≤ 200ms,批量发放(≤ 10000 条)整体 P99 ≤ 60s。
+
+失败场景:
+- 用户在黑名单 → fail with RISK_BLOCKED
+- 用户已达领券上限 → fail with LIMIT_REACHED
+- 活动已过期 → fail with ACTIVITY_EXPIRED
+```
+
+合并动作:找到 `specs/coupon-management.md` 里的 `### 优惠券发放` 块,整块替换。
+
+### REMOVED
+
+删除 requirement。
+
+```markdown
+## REMOVED: 优惠券临时冻结
+
+该能力已于 v2.3 弃用,请使用"批量撤销"替代。
+```
+
+合并动作:找到 `### 优惠券临时冻结` 块,从 spec 中删除;delta 里的说明保留到 archive(不进 spec)。
+
+### RENAMED(可选)
+
+```markdown
+## RENAMED: 优惠券锁定 -> 优惠券冻结
+```
+
+合并:找 `### 优惠券锁定`,rename heading,保留内容。
+
+---
+
+## heading 的对齐规则
+
+**匹配是字面 + trim + 空白规范化后的 exact match**:
+
+- 大小写:敏感(`优惠券发放` ≠ `优惠券发放 `)
+- 空格:trim 两端 + 内部多空格合一
+- 标点:敏感
+- level:必须 `### `(3 级),其他级别不参与匹配
+
+错误示例:
+
+```markdown
+# delta
+## MODIFIED: 优惠券 发放     ← 中间有空格,不匹配 specs 里 "优惠券发放"
+```
+
+---
+
+## 多个 delta 的合并顺序
+
+```
+delta/a.md
+delta/b.md
+delta/c.md
+```
+
+CLI 按字母序处理。
+
+同一个 spec 文件如果被多个 delta 影响(同一次 slug 不应该这样,但允许),按字母序依次应用;后者看到的是前者应用后的状态。
+
+跨 slug 的并行:不是 archive 的职责,见 [`conflict-resolution.md`](conflict-resolution.md)。
+
+---
+
+## 新 capability 的处理
+
+如果 delta 文件名对应的 spec **不存在**,archive 把整个 delta 当作新 spec 内容:
+
+delta `coupon-batch-grant.md`:
+
+```markdown
+## ADDED: 批量发放请求入参
+
+### 批量发放请求入参
+
+接口:POST /api/v1/coupons/batch-grant
+
+请求 body:
+- activityId: 必填
+- users: 必填,数组,≤ 10000
+- batchId: 可选,若传则幂等
+
+## ADDED: 批量发放响应
+
+### 批量发放响应
+
+- grantedCount: int
+- failedCount: int
+- failedReasons: array of {userId, reason, code}
+...
+```
+
+archive 产出 `specs/coupon-batch-grant.md`:
+
+```markdown
+# Capability: coupon-batch-grant
+
+## Requirements
+
+### 批量发放请求入参
+...
+
+### 批量发放响应
+...
+```
+
+顶部 frontmatter / 标题 template 在 `devflow init` 时可配。
+
+---
+
+## 已有 spec + delta 的合并细节
+
+假设 `specs/coupon-management.md` 原有:
+
+```markdown
+# Capability: coupon-management
+
+## Requirements
+
+### 优惠券发放
+
+系统 SHALL 支持单条发放,P99 ≤ 200ms。
+...
+
+### 优惠券查询
+
+...
+
+### 优惠券撤销
+
+...
+```
+
+delta:
+
+```markdown
+## MODIFIED: 优惠券发放
+### 优惠券发放
+系统 SHALL 支持单条或批量发放,...
+
+## ADDED: 批量发放优惠券
+### 批量发放优惠券
+系统 SHALL 支持 ≤ 10000 条 ...
+```
+
+合并后:
+
+```markdown
+# Capability: coupon-management
+
+## Requirements
+
+### 优惠券发放
+系统 SHALL 支持单条或批量发放,...        ← MODIFIED
+
+### 优惠券查询
+...
+
+### 优惠券撤销
+...
+
+### 批量发放优惠券                          ← ADDED
+系统 SHALL 支持 ≤ 10000 条 ...
+```
+
+顺序:ADDED 默认 append 到最后;若要精确位置,用:
+
+```markdown
+## ADDED-AFTER: "优惠券发放"
+
+### 批量发放优惠券
+...
+```
+
+---
+
+## Frontmatter 和 metadata
+
+spec 文件推荐结构:
+
+```markdown
+---
+capability: coupon-management
+status: active
+owner: @team-coupon
+lastUpdated: 2026-04-24
+lastChange: coupon-batch-grant
+relatedChanges:
+  - 2026-03-10-coupon-activity
+  - 2026-04-24-coupon-batch-grant
+---
+
+# Capability: coupon-management
+
+<description>
+
+## Requirements
+...
+```
+
+archive 会维护:
+
+- `lastUpdated`:当次 archive 时间
+- `lastChange`:当次 slug
+- `relatedChanges`:append 当次 slug
+
+owner / status 等字段 archive 不动(project 自己维护)。
+
+---
+
+## 边界 case
+
+### delta 为空(只有 `learnings.md` 无 delta)
+
+没 spec 变更,archive 只做"移动文件夹 + 记录归档时间"。
+
+### delta 只修一个字段
+
+仍然要整块替换 MODIFIED 的 block。不支持"只替换某行"这种细粒度。
+
+理由:
+
+- 粗粒度更可靠(语法无关)
+- 细粒度 diff 冲突难处理
+- 写 delta 时作者要思考清楚整个 block 现在应该是什么样
+
+### RENAMED + MODIFIED 同时发生
+
+先 RENAMED,后 MODIFIED(对新 heading)。或等价:用一个 MODIFIED 用新 heading + 新内容。
+
+### 删除整个 capability
+
+delta 是 `## DELETE_FILE`:
+
+```markdown
+## DELETE_FILE
+
+本 capability 整体废弃,能力迁移到 `coupon-batch-management` capability。
+```
+
+archive 删除 `specs/<capability>.md`(移到 `specs/_deprecated/`)。
+
+### 两个 slug 同时 archive(不应该但允许)
+
+按 archive 命令执行顺序处理。第二个 archive 看到的是第一个应用后的状态。
+
+如果第二个 delta 基于旧状态写,会发生 heading mismatch → conflict → 需协调。
+
+---
+
+## validate
+
+archive 后 CLI 跑 `devflow specs validate`:
+
+- 每个 capability 文件 `## Requirements` section 必须存在
+- 每个 `### heading` 在同一文件内唯一
+- 所有 requirement 有实质内容(非空 block)
+- lastUpdated 不晚于当前时间
+- 不存在交叉引用到已删除 capability
+
+validate 不阻塞 archive(先归档,再告警),但 `devflow doctor` 会把 validate error 当 concern。
+
+---
+
+## 版本与 Git
+
+推荐 archive 后:
+
+```bash
+git add devflow/specs/ devflow/archive/
+git commit -m "archive: <slug> — applied spec deltas"
+```
+
+commit message 模板 archive CLI 会生成,用户 review 后 commit。
+
+不推荐:
+
+- 把 spec merge 和业务 code 放同一个 commit(archive 独立)
+- force push specs(历史要稳定)
+- rebase squash spec commits(保留 archive 的时间线)
+
+---
+
+## 和 `devflow/archive/` 的关系
+
+archive 后的 `devflow/archive/<date>-<slug>/`:
+
+- 快照,不改动
+- 反查用:查历史"当时是什么需求、什么设计"
+- specs 里的 `relatedChanges[]` 指回 archive
+
+archive 不进 CI build,不打包到 npm,但进 git(长期知识资产)。
+
+---
+
+## 常见坑
+
+- delta 写在老 spec 基线上,上游已 merge 了其他 slug 的 delta,heading 漂移
+- delta 的 heading 用了 emoji / 非标点,spec 的 heading 无 → 匹配不到
+- 忘了写 delta,只改 code,spec 遗漏(下一个 change 踩坑)
+- 在 delta 里写 "TODO: 待补" → 归档时堂而皇之进 spec → spec 变垃圾堆
+- MODIFIED 内容和 spec 现状差不多(说明没实际改动),浪费 merge 计算

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: devflow-brainstorm
+description: |
+  devflow-kit 流程中，在用户**没有**任何外部材料(没 PRD / 没 JIRA / 没 Wiki / 没 incident)、只有一个模糊想法
+  时的前置硬闸。把"我想做 X" 逼问成"可写进 proposal.md 的问题框架"。当用户说 "我想加一个 X"
+  / "看看能不能做个 Y" / "帮我规划一下 Z" 且没给外部链接时,**必须**触发本 skill,不要直接跳
+  design 或写代码。若用户其实有 URL / issue 在手只是没贴出来,追问一下,能走 `devflow ingest` 就
+  走,brainstorm 不是 ingest 的替代。
+when_to_use: |
+  `devflow new <slug>` 之后、`devflow requirement` 之前的窗口。典型触发:用户纯自然语言描述一个想法,
+  没有任何可 ingest 的外部材料。L1 bug 通常不经过 brainstorm(走 ingest incident 或直接
+  requirement)。
+---
+
+# brainstorm
+
+这是 `requirement-analysis` 前的**硬闸**。目标不是"头脑风暴想点子",而是**把一个模糊想法逼成可决策的问题框架**:问题是什么、为什么现在做、边界在哪、成功怎么量。
+
+## 前置检查(任一缺失则先修)
+
+| 输入 | 必需 | 缺失时 |
+| --- | --- | --- |
+| `devflow/changes/<slug>/proposal.md` 骨架 | 是 | 先跑 `devflow new <slug>` |
+| 用户的原始输入(一段自然语言) | 是 | 追问用户,不能凭空 brainstorm |
+| `devflow/config.json` 的 `detect.language` / `detect.project` | 否(有更佳) | 用于判断代码影响面 |
+
+### 必须先问一个问题(防误用)
+
+进入 brainstorm 的第一动作:
+
+> "你这个想法在哪儿聊过?有没有 PRD / Wiki / 飞书文档 / issue?有的话我直接 ingest,brainstorm 只在完全没材料时用。"
+
+用户说"没有" → 进入 brainstorm 正常流程。
+用户说"有,我找找" → 等他给,拿到后走 `devflow ingest`,brainstorm 结束(不跑空)。
+
+## 产物
+
+编辑 `devflow/changes/<slug>/proposal.md`,必填以下 6 段:
+
+| Section | 一句话描述 | 字数建议 |
+| --- | --- | --- |
+| **Problem** | 用户的原话,或用户视角的一句话描述 | ≤ 30 字 |
+| **Why now** | 为什么是这周/这季度做而不是下季度 | 1-2 句 |
+| **Constraints** | 时间 / 现有代码 / 不能破坏的东西 | 3-5 项 |
+| **Success criteria** | 可测量的成功标准 | 2-4 项,必须含数字或二值判定 |
+| **Out of scope** | 显式列出本次**不做**的东西 | 3-5 项,越具体越好 |
+| **Recommended level** | L1/L2/L3 + 依据 | 一句结论,依据参见 `df-orchestrator/references/complexity-grading.md` |
+
+详细字段语义与反例见 [`references/proposal-template.md`](references/proposal-template.md)。
+
+## 提问方法论(核心)
+
+brainstorm 不是"问一堆问题",而是"**用尽可能少的问题**把 6 段 proposal 凑齐"。硬约束:
+
+- **一次一个问题**,不要炮连珠;用户答完重述理解给用户确认再问下一个
+- **最多 5 个问题**,超过说明你没抓住关键;超过 5 个还问不清 → 建议用户先 `devflow ingest` 外部材料或 `devflow new` 作废重来
+- **不准问"技术实现细节"**(如"你想用 Redis 还是 MySQL?"),那是 tech-spec 的事
+- **不准问多个平行问题**(如"what X and Y and Z?"),会让用户 overwhelmed
+
+问题的挑选顺序和套路见 [`references/question-catalog.md`](references/question-catalog.md),按问题类型(新功能 / 改进 / bug-driven / refactor / 合规驱动)有不同的问法集。
+
+## 5 个标准问题(按需挑 3-5 个用)
+
+| # | 问题 | 回答去哪个 section |
+| --- | --- | --- |
+| Q1 | 谁受益?怎么发现 / 触达? | Problem + Why now |
+| Q2 | 成功长什么样?能给个数字吗? | Success criteria |
+| Q3 | 哪部分代码最可能被改? | Constraints + Recommended level |
+| Q4 | 有什么必须保留不能破坏的? | Constraints |
+| Q5 | 本次明确不做什么? | Out of scope |
+
+Q3 是**判级的关键**:用户说"登录流程"→ L2 起步;说"后台新增一个 CSV 导出"→ 大概率 L1;说"跨服务加 traceId"→ L3。详细判级规则见 orchestrator 的 `complexity-grading.md`。
+
+## 会话范式(Session Template)
+
+每次 brainstorm 由 3 个阶段组成:**框架 → 迭代 → 收敛**。每阶段的话术与示例见 [`references/session-template.md`](references/session-template.md),包括:
+
+1. 开场话术(30 秒内让用户知道接下来要做啥,不是闲聊)
+2. 迭代问答(单问 → 确认 → 深化)
+3. 收敛产物(把零散回答组织成 proposal.md 的 6 个 section)
+
+## 硬闸(Done Criteria)
+
+`devflow propose`(或本 skill 判自己完成) 前必须满足:
+
+- [ ] proposal.md 的 6 个 section 全部非空
+- [ ] Success criteria 至少 1 条是**可测量的**(有数字 / 二值,"更好用 / 更快" 不算)
+- [ ] Out of scope 至少 2 条具体项(不是 "其他都不做")
+- [ ] Recommended level 写了并给出判定依据
+
+未满足 → 继续追问;仍不满足 → 回报 `NEEDS_INPUT`,由 orchestrator 转给用户。
+
+## 反模式(见过的全错法)
+
+- **brainstorm 当 design 做**:问"数据库选型 / 索引策略 / 并发方案"。这些在 tech-spec 做,在 brainstorm 问会让用户方案先行,需求反而不清。
+- **brainstorm 当 scoping 做**:试图在 brainstorm 里把需求拆到"story-by-story"。那是 requirement-analysis 的活;brainstorm 只框定题目不展开细节。
+- **同时输出 2-3 个方案让用户选**:brainstorm 的产出是**一个框定好的问题**,不是"选项 A/B/C";方案比较放 tech-spec。
+- **问题炮连珠**:一次问 5 个问题,用户只答第 1 个其他忘了 → 假装后面 4 个都得到默认值,后续 phase 炸。
+- **用户说"你帮我想"就真的全凭猜**:遇到这种,要么给用户 2 个**选择题**而不是开放题(降低用户心力),要么回报 `NEEDS_INPUT` 叫 orchestrator 把球踢回去。
+- **没问 Out of scope 就结束**:漏掉 scope 边界会在 apply / review 阶段反复返工;必须显式问。
+- **跳过 Problem 直接写 "Recommended level"**:顺序不能反;没定义 Problem 就判级是瞎蒙。
+
+## 完成状态协议
+
+完成时输出:
+
+```
+---STATUS---
+result: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_INPUT
+outputs:
+  - devflow/changes/<slug>/proposal.md
+recommendedLevel: L1 | L2 | L3
+nextAction: devflow requirement
+---END_STATUS---
+```
+
+orchestrator 接到 DONE → 进入 requirement-analysis。
+
+## 参考
+
+- [`references/proposal-template.md`](references/proposal-template.md) — proposal.md 6 段的详细模板、正反例、字段边界
+- [`references/question-catalog.md`](references/question-catalog.md) — 按任务类型挑问题(新功能/改进/bug-driven/refactor/合规/性能)
+- [`references/session-template.md`](references/session-template.md) — 开场/迭代/收敛 3 阶段话术与完整对话示例