@chenguangyao/devflow-kit 0.1.43

package/skills/brainstorm/references/proposal-template.md

@@ -0,0 +1,244 @@
+# brainstorm / proposal-template
+
+`proposal.md` 的 6 段详细模板、正反例、字段边界。
+
+---
+
+## 模板
+
+```markdown
+---
+slug: <slug>
+createdAt: <ISO>
+level: L1 | L2 | L3
+source: brainstorm                       # 固定,与 ingest 区分
+---
+
+# Proposal: <one-line title>
+
+## Problem
+<用户原话 / 用户视角的一句话描述问题。不要加你的解读。>
+
+## Why now
+<为什么是本周期做,不是下周期。>
+
+## Constraints
+- <现有代码的约束(不能破坏 X、必须兼容 Y)>
+- <时间约束(deadline)>
+- <人 / 依赖约束(跨团队要对齐)>
+- <技术债约束(目前代码是什么样)>
+
+## Success criteria
+- <必须可量化;不能全是"更好/更快/更稳定">
+- ...
+
+## Out of scope
+- <本次明确不做 A>
+- <本次明确不做 B>
+- ...
+
+## Recommended level
+<L1 | L2 | L3>,依据:<至少 2 条引用自 complexity-grading.md 的维度>
+```
+
+---
+
+## 字段详述(含正反例)
+
+### 1. Problem
+
+**是什么**:用户看到的现象 / 痛点,用**用户的语言**而不是工程师的语言。
+
+**反例**:
+
+> ~~引入 Redis 缓存优化接口性能~~
+> (这是 "solution",不是 "problem"。用户不要求你上 Redis。)
+
+**正例**:
+
+> 用户投诉:商品详情页首次加载超过 3 秒,购物车转化率下降 8%。
+
+**判定**:
+
+- 是否描述了**现象** / **痛点** → 是
+- 是否提了**具体方案** → 不能提(那是 tech-spec 的事)
+- 是否带了**量化信号** → 最好带,能让后面的 Success criteria 有对照
+
+---
+
+### 2. Why now
+
+**是什么**:回答"为什么不是下季度 / 不是下半年"。防止做错优先级。
+
+**好信号**:
+
+- 某个业务指标到了红线(Q3 GMV 下降 5%)
+- 某个截止日期硬(9/30 合规截止)
+- 依赖方 deadline(下游团队 Q4 要我们支持 X)
+- 技术债已到临界(某库 EOL 12/31)
+
+**反例**:
+
+> ~~看着用户抱怨有点多,做一下。~~
+> (没有 urgency,不回答 "为什么现在")
+
+**正例**:
+
+> 商家 Q3 大促前要开启此类活动;9/30 前必须上线。
+
+---
+
+### 3. Constraints
+
+**是什么**:这次做事时必须**遵守**的边界。
+
+分 4 类:
+
+| 类型 | 例子 |
+| --- | --- |
+| **代码 / 架构** | 不能破坏现有 `/api/v1/coupon/*` 契约;必须兼容 iOS 2.3 及之前 |
+| **时间** | 9/25 前提测,9/30 灰度 |
+| **人 / 依赖** | 前端由 Alice 配合,依赖 billing 服务的 grantAPI(尚未上线,依赖方 9/20 好) |
+| **技术债** | 当前 grant 表未分表,数据量 ×10 后性能存疑 |
+
+**反例**:
+
+> ~~没什么约束,随便做。~~
+> (真的一项都列不出来 → 八成是没想清楚;回去多问一轮)
+
+**数量建议**:3-5 条,超过说明你在堆废话;少于 2 条说明 brainstorm 不充分。
+
+---
+
+### 4. Success criteria
+
+**是什么**:本次任务 "完成" 的客观判据。必须**可量化 / 可验收**。
+
+好的成功标准要满足 **SMART 原则**:**S**pecific、**M**easurable、**A**chievable、**R**elevant、**T**ime-bound。
+
+**反例**:
+
+> ~~~
+> - 用户体验更好
+> - 系统更稳定
+> - 代码更易维护
+> ~~~
+> (没有一个可量化)
+
+**正例**:
+
+> - 商品详情页 P99 < 1.5s(当前 3.2s)
+> - 购物车转化率 Q4 末 > 7.5%(当前 7.0%)
+> - 新接口 QPS ≥ 2000 时 error rate < 0.1%
+> - 对外契约完全兼容,旧客户端无感知(对比测试通过)
+
+**判定规则**:
+
+- 每条都必须能用一个**数字**或**二值判定**验收,否则打回
+- 数字要有**对照**(当前 vs 目标),否则没参考系
+- 至少 1 条是"用户侧指标"(GMV / 转化率 / 延迟 / 错误率),不能全是"我们内部自测通过"
+
+---
+
+### 5. Out of scope
+
+**是什么**:**显式写明**本次不做的事情。防止后续 scope creep。
+
+**反例**:
+
+> ~~~
+> - 其他功能不做
+> - 暂时不考虑性能
+> ~~~
+> (太泛,相当于没说)
+
+**正例**:
+
+> - 不做**跨店铺**优惠券合并(下个迭代)
+> - 不做**退款场景**的优惠券返还(现有流程沿用)
+> - 不做**H5 页面**改造(只改 App 和 Web)
+> - 不做**运营后台**的**批量发券**(有其他 JIRA 跟进)
+
+**套路**:把用户可能**误会你要做**的事、**下个迭代更合适做**的事、**别的团队负责**的事全部写进来。宁多勿少。
+
+---
+
+### 6. Recommended level
+
+**是什么**:本次任务复杂度。由 orchestrator 的 `complexity-grading.md` 逐维度判定。
+
+**格式**:
+
+> **L2**,依据:
+> - 代码规模维度 → L2(预计改 4-6 文件)
+> - 数据层维度 → L2(新增 1 表 + 加 2 列)
+> - 对外契约 → L2(新增 2 接口)
+> - 并发 → L1(单表事务足够)
+> 其余维度 → L1。综合取最高 = L2。
+
+**反例**:
+
+> ~~L2(中等复杂度)~~
+> (没有依据,不能审计)
+
+---
+
+## 完整填写样例(L2 新功能)
+
+```markdown
+---
+slug: add-coupon-batch-grant
+createdAt: 2026-04-24T09:00:00+08:00
+level: L2
+source: brainstorm
+---
+
+# Proposal: 批量发放优惠券给指定用户群
+
+## Problem
+运营侧反馈:单次只能发一人,运营做一次营销要手动发 200+ 次。
+
+## Why now
+Q4 大促前要配合 3 场活动,运营预计人均操作 300 次/场;人肉发券不可能完成。
+
+## Constraints
+- 不能破坏现有 `/api/v1/coupon/grant` 单人发放接口
+- 必须兼容现有风控规则(同人同模板 24h 内不可重复领)
+- 数据库不允许分表改造(另一迭代独立推进)
+- 9/25 前提测,10/1 大促前上线
+
+## Success criteria
+- 单次发放 ≤ 1000 人,接口 P99 < 3s
+- 错误率 < 0.1%(含部分失败的场景)
+- 运营后台操作耗时 < 1 分钟/场(当前 > 1 小时)
+- 风控拦截准确率与单发一致(误拦 < 0.01%)
+
+## Out of scope
+- 不做**跨店铺**批量
+- 不做**H5 运营页**改造(只改后台)
+- 不做**券模板**的新增字段(另有 SCRUM-15900)
+- 不做**对账 / 结算**侧调整(下阶段做)
+
+## Recommended level
+**L2**,依据:
+- 代码规模 → L2(预计 6-8 文件)
+- 数据层 → L2(无 DDL,只加索引优化批量查询)
+- 对外契约 → L2(新增 1 接口,对 legacy 兼容)
+- 并发 → L2(批量落库用事务 + 风控在应用层串行化)
+- 安全 → L1
+- 监控 → L2(新增 QPS / 耗时 / 错误率指标)
+综合 = L2。若大促前发现需要分布式锁(跨机房)会升 L3。
+```
+
+---
+
+## 与下游的交接
+
+`requirement-analysis` skill 的 Round 1 会**逐段**读这个 proposal:
+
+- Problem / Why now → copy 到 `requirement.md` 的"Business background"
+- Constraints / Out of scope → 约束场景生成"Non-functional" 和"Scope"
+- Success criteria → 生成**验收标准**骨架(acceptance criteria)
+- Recommended level → 写入 `state.level`,影响 tests / reports 的强制项
+
+**brainstorm 填得越细,requirement-analysis 就越快收敛**,不要在 brainstorm 偷懒。

package/skills/brainstorm/references/question-catalog.md

@@ -0,0 +1,168 @@
+# brainstorm / question-catalog
+
+按任务类型挑问题。brainstorm 硬约束"一次一个 / 最多 5 个",所以要**精挑最值钱的那几个**。
+
+---
+
+## 先识别任务类型
+
+从用户的原话里识别它属于哪一类,然后用对应类别的问题集。
+
+| 类型 | 信号词 | 典型表述 |
+| --- | --- | --- |
+| **NEW_FEATURE** | "新增"、"加一个"、"做一个"、"上一个新功能" | "我想加一个批量发券的能力" |
+| **IMPROVEMENT** | "优化"、"改进"、"加速"、"体验更好" | "首页加载太慢想优化一下" |
+| **BUG_DRIVEN** | "修 / 解决 / 修复 / 它不工作了" | "发现优惠券领取偶尔失败" |
+| **REFACTOR** | "重构 / 拆 / 合并 / 整理 / 解耦" | "想把用户模块拆成领域模型" |
+| **COMPLIANCE** | "合规 / 审计 / 隐私 / 监管 / GDPR" | "监管要我们加操作日志" |
+| **PERFORMANCE** | "性能 / 延迟 / QPS / 慢 / 扩容" | "接口 P99 压不下来" |
+| **MIGRATION** | "替换 / 升级 / 迁移 / 去掉旧的" | "把 MongoDB 迁到 MySQL" |
+
+识别不准 → 问一个歧义性问题先定类型,例如:
+
+> "你这个更像'加一个全新能力'还是'现有能力有问题要修'?"
+
+---
+
+## NEW_FEATURE — 5 个候选问题
+
+| # | 问题 | 默认必问 | 能获得什么 |
+| --- | --- | --- | --- |
+| Q1 | 这个功能最终**谁在用**?他们在哪个场景下用? | 是 | Problem + Why now |
+| Q2 | 成功了能看到什么**数字**?(转化率/使用率/满意度) | 是 | Success criteria |
+| Q3 | 你心目中的最小可用版本是什么? | 是 | Scope / Out of scope |
+| Q4 | 如果只能做一半,优先做哪一半? | 视情况 | Out of scope |
+| Q5 | 是否有**必须**兼容或**必须**不破坏的现状? | 视情况 | Constraints |
+
+---
+
+## IMPROVEMENT — 5 个候选问题
+
+| # | 问题 | 能获得什么 |
+| --- | --- | --- |
+| Q1 | 现在有多差?(具体数据:延迟、错误率、主观反馈) | Problem(含 baseline) |
+| Q2 | 改到多好算"好"?(目标值) | Success criteria |
+| Q3 | 是哪一部分最痛?(模块/路径/用户群) | Scope |
+| Q4 | 有没有**推迟过**类似的改进?为什么现在做? | Why now |
+| Q5 | 能接受**短期用体验**换**长期性能**吗?(如加 loading、降精度) | Constraints |
+
+---
+
+## BUG_DRIVEN — 5 个候选问题
+
+优先走 `devflow ingest incident:<id>` 而不是 brainstorm。只有当 bug 没有 incident ID 且不是线上紧急时才 brainstorm。
+
+| # | 问题 | 能获得什么 |
+| --- | --- | --- |
+| Q1 | 具体怎么复现? | Problem(清晰复现步骤) |
+| Q2 | 影响多少用户 / 影响多大? | Recommended level |
+| Q3 | 想修表现还是修根因?(短期 vs 长期) | Scope |
+| Q4 | 是否需要加监控 / 告警? | Constraints / Success |
+| Q5 | 有没有已知的 workaround?现在能用吗? | Why now |
+
+---
+
+## REFACTOR — 5 个候选问题
+
+重构是**最危险**的任务类型,问错或问少会触发"纯重构无业务价值 + 引入风险"的灾难。
+
+| # | 问题 | 必问 | 能获得什么 |
+| --- | --- | --- | --- |
+| Q1 | 为什么**现在**做?有业务推动还是纯工程? | 是 | Why now(纯工程要警惕) |
+| Q2 | 不重构会怎样?最坏多痛? | 是 | Problem |
+| Q3 | 本次重构的**边界**在哪?不碰哪部分? | 是 | Out of scope(重构尤其要明) |
+| Q4 | 怎么证明重构成功?(行为等价 + 哪些指标不变 + 哪些指标改善) | 是 | Success criteria |
+| Q5 | 有覆盖当前行为的测试吗?没有的话先补再重构 | 视情况 | Constraints |
+
+**orchestrator 特别提示**:如果 Q1 得到的是"没业务推动,纯看着乱想整整",默认推荐**不做**,或先补测试再说。重构无业务推动 = 高风险无收益。
+
+---
+
+## COMPLIANCE — 5 个候选问题
+
+| # | 问题 | 能获得什么 |
+| --- | --- | --- |
+| Q1 | 法规名称 / 审计 ID / 政策文档链接? | Problem(必须有明确依据) |
+| Q2 | 最晚什么时候必须上线?(合规通常硬 deadline) | Why now |
+| Q3 | 哪些字段 / 行为涉及(数据范围)? | Scope |
+| Q4 | 是否需要留**审计日志**可查?保留多久? | Constraints |
+| Q5 | 违规后果是什么?(罚款 / 下架 / 警告) | Recommended level |
+
+合规类任务几乎必然是 L2+,且 deliver 时通常要求额外审计 checklist。
+
+---
+
+## PERFORMANCE — 5 个候选问题
+
+| # | 问题 | 能获得什么 |
+| --- | --- | --- |
+| Q1 | 现在的 baseline?(QPS / 延迟 / 错误率 / 资源利用) | Problem(必须量化) |
+| Q2 | 目标?(具体数字 + 优先级指标) | Success criteria |
+| Q3 | 已知瓶颈在哪?(有没有 profiling 结果) | Scope |
+| Q4 | 能接受哪种代价?(成本 / 复杂度 / 一致性降级) | Constraints |
+| Q5 | 是稳态还是高峰?(稳态优化 vs 高峰扩容) | Recommended level |
+
+性能类任务建议在 brainstorm 结束前**要求用户提供 profile / APM 数据**,没数据的"感觉慢"容易做成伪优化。
+
+---
+
+## MIGRATION — 5 个候选问题
+
+| # | 问题 | 必问 | 能获得什么 |
+| --- | --- | --- | --- |
+| Q1 | 迁移什么?(一次性迁移 or 双写逐步切) | 是 | Scope |
+| Q2 | 能接受停服吗?多久? | 是 | Constraints |
+| Q3 | 成功判据?(数据一致性 / 性能 / 开关完成) | 是 | Success criteria |
+| Q4 | 回滚方案?(迁移失败怎么办) | 是 | Constraints |
+| Q5 | 增量数据怎么处理? | 视情况 | Scope |
+
+迁移类几乎必然 L3,且要求 design.md 有完整灰度 + 回滚方案。
+
+---
+
+## 通用的"避雷问题"(任何类型都要考虑问)
+
+如果前面类别的 5 个问题还没触达下面几个点,补问:
+
+1. **谁是这次任务的最终决策人?**(涉及多 stakeholder 的 L2/L3 必问)
+2. **Deadline 硬还是软?**(影响 scope 取舍)
+3. **有没有类似的功能 / 事故 / 迁移在其他项目做过?**(可抄经验)
+4. **成功了之后下一步是什么?**(防止短视设计,L3 必问)
+
+---
+
+## 问得不好的反模式
+
+| 错法 | 为什么错 | 怎么改 |
+| --- | --- | --- |
+| "你想用什么技术栈?" | 技术选型属于 tech-spec | 不问。brainstorm 专注 **问题**,不问 **方案** |
+| "你希望哪个模块来实现?" | 模块归属属于 design | 改问"哪些现有能力可以复用" |
+| "性能要求是多少?QPS?延迟?缓存策略?并发量?" | 一次问 4 个 | 拆成单问,先问最重要的 |
+| "要不要加监控?" | 0/1 二值问题,答了也没信息 | 改问"希望在**哪些场景**下看到什么" |
+| "你想做 A、B、C 哪一个?" | 方案 A/B/C 是 tech-spec 的事 | 改问"**问题**是什么" |
+| "有什么想法?" | 太开放,用户不知道该答啥 | 给选项或约束范围 |
+
+---
+
+## 识别用户答不出时
+
+如果用户对某个关键问题回答含糊(如 "嗯…我也不确定"),**不要强行继续**,三选一:
+
+1. **降级到选择题**:"那我给你两个选项看看哪个更接近?A: ... B: ..."
+2. **标记为 Open issue**:记到 proposal.md 的 "Risks / Open issues" section(brainstorm 阶段允许部分未定,但必须标记)
+3. **建议 `devflow ingest` 外部材料**:"这个问题听起来 PM 更清楚,有没有他们写的文档?"
+
+---
+
+## 对话节奏
+
+- 一个问题 + 用户回答 + 你的 1 句话复述确认 → 下一个问题
+- 不要在 chat 里长段复述整个 proposal.md;在 **最后**收敛阶段一次性展示
+- 问题之间保持**一致性检查**:用户答的 Q3 如果与 Q1 矛盾,立即指出问他
+- 单次 session 控制在 **10 分钟 / 5 轮问答**,超了提醒用户 brainstorm 该收了
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 只给了 5 个通用问题。本文按 7 种任务类型细化问题集,brainstorm 实际运行时按类型挑集。也列了避雷问题和提问节奏,防止 brainstorm 退化成"开放式头脑风暴"。

package/skills/brainstorm/references/session-template.md

@@ -0,0 +1,184 @@
+# brainstorm / session-template
+
+一次 brainstorm 对话的 3 阶段模板:**框架 → 迭代 → 收敛**。每阶段带完整话术与真实示例。
+
+---
+
+## 阶段 1 — 框架(30 秒内)
+
+### 目标
+
+在 30 秒内让用户**知道接下来要干什么**,并**先排除 ingest 路径**。
+
+### 开场话术(复制即可用)
+
+```
+准备进入 brainstorm。规则:
+  1. 我会问 3-5 个问题,每次 1 个,不是一次问一串。
+  2. 你答完我会复述理解,你可以立刻纠正。
+  3. 5 问后我会把要点整理成 proposal.md(6 个 section)。
+
+但先确认一下:
+
+  ◉ 这个想法在哪儿聊过?有 PRD / Wiki / 飞书文档 / JIRA issue / 聊天记录吗?
+    - 有 → 请贴过来,我 `devflow ingest` 走一遍比 brainstorm 高效
+    - 没有 → 我们开始 brainstorm
+```
+
+### 分支
+
+| 用户回答 | 动作 |
+| --- | --- |
+| "有,我找找" | **终止 brainstorm**;等拿到后 `devflow ingest`。这 30 秒没浪费 —— 防止了无意义的 brainstorm |
+| "没有,现在就聊" | 进入阶段 2 |
+| "有一点点,就是微信聊天" | 请用户贴聊天记录截图或转文字;作为 `refs/chat-excerpt.md` 入库,继续 brainstorm |
+| "我也不确定,你觉得呢" | 不允许;提醒 brainstorm 必须由用户主导。无法主导 → 建议先跟 PM 聊一次 |
+
+---
+
+## 阶段 2 — 迭代(最多 5 轮)
+
+每轮 = 1 问 + 1 答 + 1 复述确认。
+
+### 单轮话术
+
+```
+Q<N>: <问题,从 question-catalog.md 按类型挑>
+
+[用户回答]
+
+理解:<把用户回答复述成一句话>
+这个对吗?
+```
+
+### 迭代节奏
+
+```
+Q1 → 回答 → 复述确认 ✓
+Q2 → 回答 → 复述确认 ✓
+Q3 → 回答 → 复述确认 ✗ → 用户纠正 → 再复述确认 ✓
+Q4 → 回答 → 复述确认 ✓
+Q5 → 回答 → 复述确认 ✓
+进入收敛阶段
+```
+
+### 复述的目的(不是闲话)
+
+1. **给用户纠正机会**:他回答得快,你复述慢,他发现自己说错就改
+2. **锚定上下文**:下一个问题基于前一个确认的事实,防止飘
+3. **给自己检查矛盾的机会**:复述时你自然在脑中组织 proposal.md,矛盾会暴露
+
+### 完整对话示例(NEW_FEATURE 类)
+
+> **User**: 我想做一个批量发优惠券的功能。
+
+> **Skill**: 准备进入 brainstorm...[开场话术]...这个想法在哪儿聊过?有 PRD 吗?
+
+> **User**: 暂时没有,运营上周提的,我们自己决定做。
+
+> **Skill**: 好,我们开始。
+>
+> **Q1**: 这个批量发券最终谁在用?他们在什么场景下用?
+
+> **User**: 运营同学,主要是大促前要给一批用户发活动券,现在一次只能发一个人,要手动发 300 次。
+
+> **Skill**: 理解:使用者是**运营**,场景是**大促前给目标用户群(200-300 人规模)批量发放活动券**,痛点是**当前只能单人发放,需要手动重复几百次**。对吗?
+
+> **User**: 对,就是这样。有时候甚至上千人。
+
+> **Skill**: 更新:规模**最高 1000+ 人**。继续。
+>
+> **Q2**: 成功了能看到什么**数字**?比如运营操作时长下降多少、发放成功率多少?
+
+> **User**: 至少时长降到原来的 1/10 吧,成功率不低于单发。
+
+> **Skill**: 理解:成功标准是**单场发放耗时 ≤ 6 分钟**(当前 ≈ 1 小时)、**成功率 ≥ 单发水平**(当前 99.9%)。对吗?
+
+> **User**: 对。
+
+> **Skill**: **Q3**: 哪部分代码最可能被改?你知道单发是在哪个模块吗?
+
+> **User**: 在 coupon-service 的 GrantController 里,风控在 RiskService。
+
+> **Skill**: 理解:主要改动在 `coupon-service/GrantController`,风控逻辑 `RiskService` 需要复用。记为 L2 信号(多文件改动 + 业务核心)。
+
+> **Skill**: **Q4**: 有没有**必须**保留、不能破坏的现状?
+
+> **User**: 单发接口不能破坏,前端还在用。风控规则要完全一致。
+
+> **Skill**: 理解:约束 ① 单发 API 契约不动;② 风控逻辑与单发一致(不能批量就 bypass)。继续。
+>
+> **Q5**: 本次明确**不做**什么?
+
+> **User**: 不做跨店铺、不做 H5 页面改造、不做退券。
+
+> **Skill**: 理解。准备收敛。
+
+---
+
+## 阶段 3 — 收敛
+
+### 动作
+
+1. 把 5 轮问答的信息按 6 个 section 组织(不重新问用户)
+2. 填 `recommendedLevel` 并给出判定依据
+3. 把完整 proposal.md 展示给用户一次,要求"最后确认"
+
+### 收敛话术
+
+```
+准备好 proposal.md 了,给你过一遍:
+
+---
+[完整 proposal.md 内容]
+---
+
+请确认:
+  1. Problem / Why now 的描述是否准确?
+  2. Success criteria 的数字(6 分钟 / 1000 人 / 99.9%)能接受吗?
+  3. Out of scope 的 4 条是否有遗漏?
+  4. Recommended level = L2 是否同意?
+
+如果都 OK,我就落文件 → `devflow requirement` 进入下一步。
+有要改的告诉我,我现场改。
+```
+
+### 分支
+
+| 用户反馈 | 动作 |
+| --- | --- |
+| "OK,落" | 写入 `proposal.md`,输出 `DONE` 状态协议 |
+| "改一下 X 段" | 修改,再次整段展示,再次确认 |
+| "嗯…再想想" | 记为 `NEEDS_INPUT`,提示用户考虑好后再 `devflow brainstorm --resume` |
+| "算了不做了" | 建议 `devflow deliver --mode=discard --reason=...`,不要留垃圾 change 在目录里 |
+
+---
+
+## 常见的偏离 & 回正
+
+| 偏离 | 表现 | 回正 |
+| --- | --- | --- |
+| **炮连珠** | 一次问 3 个子问题 | 中断,选最重要的一个问,其余后面再问 |
+| **方案先行** | 问着问着变成"你想用 Redis 还是 MySQL" | 记住 brainstorm 不选方案,停,回到 Q-catalog |
+| **无止境澄清** | 5 问后还问第 6、7 个 | 5 问到了,有没答清的标为 Open issue,收敛 |
+| **用户反问你** | "你觉得这个功能该怎么做?" | 明确"brainstorm 期我不给方案,方案在 tech-spec";回到 Q |
+| **跑题闲聊** | 聊到公司八卦 / 其他 feature | 温和拉回:"回到 <slug>,Q3 是..." |
+
+---
+
+## 单次 session 时间预算
+
+| 阶段 | 目标时间 |
+| --- | --- |
+| 框架 | ≤ 30 秒 |
+| 迭代 | 每轮 1-2 分钟,共 5-10 分钟 |
+| 收敛 | 2-3 分钟 |
+| 总计 | **10 分钟以内** |
+
+超时信号:用户开始表现不耐烦("你能直接写吗" / "我没时间"),说明你问得太细或太慢。
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了硬约束(一次一个 / 最多 5 个 / 6 段 proposal)。本文展示**完整对话长什么样**、偏离了怎么回正、多长时间合理。对 agent 来说,本文是"看懂 brainstorm 是一段 conversation 而不是一次 form 填写"的关键。

package/skills/ci-fix/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: devflow-ci-fix
+description: |
+  devflow-kit CI / PR feedback 修复专项 skill。当 PR/MR 检查失败、GitHub/GitLab review comment 未解决、Jenkins/GitHub Actions/GitLab CI 失败时触发。
+  要求先读取 CI 日志和 review comment,完成归因后再进入 apply 修复,并在 verify/deliver 前形成"读 CI -> 定位日志 -> 修复 -> 重跑"闭环。
+when_to_use: |
+  用户说 CI 失败、PR comment、review feedback、检查没过、Jenkins 红了、GitHub Actions 失败、修一下评论时使用。deliver 前发现未通过检查也必须使用。
+---
+
+# ci-fix / pr-feedback
+
+CI 和 PR 反馈修复专项 skill。目标是把"红了,修一下"变成可审计闭环,避免 agent 不读日志就猜。
+
+## 输入
+
+- PR/MR URL 或编号。
+- CI run / job URL。
+- Jenkins build URL。
+- reviewer comment / unresolved thread。
+- 本地 `review.md` / `reports/test-report.md` / `state.json`。
+
+## 接入点
+
+| phase | 行为 |
+| --- | --- |
+| review 后 | 读取 unresolved comments,分类 MUST/SHOULD/NIT |
+| apply | 只修复已归因的问题,不要顺手扩大 scope |
+| verify | 重跑失败 job 对应的最小测试,必要时重跑全量 |
+| deliver 前 | 确认 required checks 已通过或有审计原因 |
+
+## 执行流程
+
+1. 收集失败源:CI job、日志、review comment、失败测试名称。
+2. 归因,必须写清:
+   - `code_error`:当前 diff 引入或暴露的代码问题。
+   - `env_error`:环境、凭证、网络、测试数据、runner 问题。
+   - `flake`:偶发或竞态,需要证据。
+   - `baseline`:本分支前已有失败,不能伪装成已修复。
+3. 把每个问题映射到 plan task 或新增 fix task。
+4. 执行最小修复,不要重写无关模块。
+5. 重跑对应命令;如果是远端 CI,记录重跑链接或本地等价验证。
+6. 更新 `review.md` 或 `reports/test-report.md` 的修复证据。
+
+## 输出要求
+
+每轮结束必须给出下一步卡片:
+
+```markdown
+## 下一步
+状态：DONE | NEEDS_INPUT | BLOCKED
+摘要：CI/PR feedback 修复结论
+证据：<日志链接或测试报告>
+命令：`devflow verify finalize --slug=<slug>` 或 `devflow apply --slug=<slug> --note="fix CI"`
+```
+
+## 反模式
+
+- 不读 CI 日志,直接猜测修复。
+- 只看最后 20 行,忽略第一个失败。
+- 把 reviewer 的 SHOULD/NIT 当 MUST 扩大重构。
+- CI 仍红却 deliver。
+- 本地跑了不等价命令,却声称远端 CI 已修复。
+

package/skills/ci-fix/references/loop.md

@@ -0,0 +1,25 @@
+# CI / PR feedback loop
+
+## 归因表
+
+| 类型 | 判断依据 | 下一步 |
+| --- | --- | --- |
+| code_error | 本地或远端稳定复现,和当前 diff 相关 | 回 apply 修复 |
+| env_error | URL、凭证、网络、测试数据、runner 不可用 | 修环境或记录 blocked |
+| flake | 重跑通过,无稳定复现,有竞态/超时迹象 | 标记 flake,必要时加稳定性修复 |
+| baseline | base 分支或改动前已失败 | 记录 baseline,不要归咎当前 diff |
+
+## 最小证据
+
+- 失败 job 名称和 URL。
+- 首个失败测试或错误堆栈。
+- 本地复现命令或说明为什么不能复现。
+- 修复 commit/diff 摘要。
+- 重跑结果。
+
+## PR comment 分类
+
+- MUST:会导致错误、回归、安全风险、缺少必需测试。
+- SHOULD:建议改进,不阻塞但应回应。
+- NIT:风格和小建议,可批量处理或说明暂不处理。
+