@rowansenne/workflow-run 0.29.1 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dev/SKILL.md.tpl CHANGED
@@ -20,7 +20,8 @@ description: "Explicitly requested dev workflow for feature development or bug f
20
20
  - 开工先运行 `node <skills>/workflow/scripts/resolve.mjs status`;DocNexus 必装,不可用先修复。可选增强复用 `<skills>/workflow/references/capabilities.md` 的本轮快照。
21
21
  - 先确定工作分支、已有改动的归属与需求名;切分支重新查询绑定,不替用户丢弃已有改动。
22
22
  - 规模由 agent 判定并说明,不询问规模确认;M / L 的需求理解和方案须用户确认后再实现,权限 / 资金至少按 M。
23
- - S 快速通道须用户明确同意,且 ≤3 文件、无配置 / SQL / 对外接口 / 表结构 / 权限 / 资金变更,且没有已确认的业务决定;具体资格见 F4。
23
+ - F2 先落偏业务场景的 clarification.md,供用户找产品核对;逐轮更新原问题状态、追加新问题和反馈。业务明确并完成现状调研后,再进入 F3 澄清技术约束;最终需求确认后进入 F4。
24
+ - S 快速通道须用户明确同意,且 ≤3 文件、无配置 / SQL / 对外接口 / 表结构 / 权限 / 资金变更,且没有 F2 / F3 已确认的业务决定、本次未发布正式清单且未创建完整流程运行;已有清单或运行沿用完整流程,具体资格见 F4。
24
25
  - 快速通道仍编译、测试、当前会话审查,但不 bind、不建运行、不落需求 / 方案 / 审查 / 交付文档;超限或用户要求落盘先停,回 F3(bug 回 B3)补需求文档,再进入方案。
25
26
  - 完整流程每轮审查落 `review.md`,交报告后等待明确选择修复或交付;选择交付前不创建或更新 `delivery.md`。
26
27
  - 修复后必须验证、复审并再次等选择;严重遗留风险须说明并取得明确接受,不能把一般的“交付”当作接受风险。
@@ -34,7 +35,7 @@ description: "Explicitly requested dev workflow for feature development or bug f
34
35
  ## 完整流程的运行状态
35
36
 
36
37
  确定工作分支后先 `run.mjs show`;恢复时核对 context、代码与证据,不能把“继续”当作交付选择。
37
- 非快速通道在 F3 / B3 收尾、首次落盘需求文档前 bind,再 `run.mjs start --kind feature|bug --size <规模> --input <checkpoint.json>`,补记真实完成的前置步骤;首个文档为 `requirement.md`。
38
+ 非快速通道首次落盘前 bind、start 并补记真实完成的前置步骤。需要业务清单时从 F2 创建(仅补记 Step0、F1);无需清单时在 F3 收尾需求文档前创建。bug 从 B3 创建。清单每轮发布、等待时保存 waiting_user;业务与技术约束均明确后才收尾 requirement.md 并完成 F3 / B3。
38
39
  每步完成、等待、阻塞和结束会话前 save;修复回 F5 / B4,交付进 F8 / B5。具体协议读 `<skills>/workflow/references/runs.md` 与 [execution.md](../workflow/references/execution.md)。
39
40
  交付、自检、摘要与反馈处理后,末步标 completed,再 `run.mjs complete`,保存 completed(已完成)和 completed_at;已完成运行不覆盖。
40
41
 
@@ -44,14 +45,14 @@ description: "Explicitly requested dev workflow for feature development or bug f
44
45
 
45
46
  读 [planning.md 的 F1](references/planning.md);运行 `node <skills>/workflow/scripts/knowledge.mjs dev --match <模块> --query "<需求>"`,按需拉 PRD,形成需求要点、验收标准与未定决定。
46
47
 
47
- ### F2 — 现状调研
48
+ ### F2 — 业务场景核对与现状调研
48
49
 
49
- 读 [planning.md 的 F2](references/planning.md);按本轮能力沿调用链读代码,涉及表时用 `tables.mjs --files <文件>` 定位;事实与证据进入方案依据。
50
+ 先读 [clarify.md 的 F2](references/clarify.md),在 F3 前按业务场景模板发布正式 clarification.md,供产品核对角色、操作、业务规则、异常、范围和验收;多轮更新与反馈都留在同一清单,等待时停在 F2。再按 [planning.md 的 F2](references/planning.md) 完成代码与数据调研,业务明确且调研结束后进入 F3。
50
51
  涉及远程参数或开关且已安装 nacos-config 时,按 `<skills>/nacos-config/SKILL.md` 按需读取并标明来源;无法读取时注明「未核对远程配置」,不把代码默认值当成远程实际值。
51
52
 
52
- ### F3 — 需求澄清
53
+ ### F3 — 需求澄清(偏技术约束)
53
54
 
54
- 读 [clarify.md](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);事实自己查、决定交用户。澄清后按 F4 标准判定规模与快速通道;完整流程用 `artifact.mjs finalize --kind requirement` 收尾 `requirement.md`,独立保存目标、范围、验收与决定。实现中新决定先回本步更新需求文档。
55
+ 读 [clarify.md 的 F3](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);基于已确认业务场景,查清可行性、接口兼容、数据与一致性、权限、依赖及验证条件。事实自己查,需用户取舍的技术约束给推荐并等答复;详细设计留到 F4。发现新业务问题回 F2 更新清单找产品确认。全部明确后,完整流程 finalize requirement.md、完成 F3,再进 F4。
55
56
 
56
57
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
57
58
 
@@ -104,4 +105,4 @@ description: "Explicitly requested dev workflow for feature development or bug f
104
105
 
105
106
  - 不直接写库、不改凭据文件;SQL 只生成脚本。安装新依赖、提交、推送、改写历史、删除分支须有用户授权。
106
107
  - 不改无关代码;现有代码结论引用真实文件和行号,测试没跑不能说通过。
107
- - 用户改变需求回 F3,只澄清变化部分并更新验收标准。
108
+ - 用户改变业务场景回 F2 更新清单,技术约束变化回 F3,只核对变化部分并更新验收标准。
@@ -17,6 +17,7 @@
17
17
  - 沿调用链找到**第一个**出错的位置,用证据(代码行、日志、数据、git 历史 `git log -L` / `git blame`)说明为什么错。
18
18
  - 区分根因与症状:只在出错表象处加判空 / try-catch 不算修复,除非能说明那里就是根因。
19
19
  - 检查同一根因是否在其他调用方同样存在。
20
+ - 预期业务行为还需产品确认时,按 clarify.md 的清单规则在 B3 初判规模、bind、start,逐轮发布同目录的 clarification.md 并保存等待反馈;需求明确后沿用该运行收尾需求文档。
20
21
  - 根因与修复目标明确后,按 F4 的标准判定规模与快速通道;完整流程在 B3 收尾前 bind、start,按需求模板将现象、期望、范围、验收与澄清决定写成 requirement.md,用 `artifact.mjs finalize --kind requirement` 并标 B3 completed,再进 B4。根因证据作事实依据,修复方式留在 plan.md;已有文档先核对后在草稿更新,不自动覆盖原需求。
21
22
 
22
23
  ### B4 — 修复与验证
@@ -0,0 +1,40 @@
1
+ # 业务场景待确认清单 — {{需求名}}
2
+
3
+ > 阶段:{{F2 / B3}} | 状态:{{待产品反馈 / 业务已明确}} | 轮次:{{1}} | 更新日期:{{YYYY-MM-DD}}
4
+ > 分支:{{dev分支}} | 需求来源:{{PRD 链接 / 对话}} | 下一步:{{需产品核对的问题 / 现状调研与 F3 技术澄清}}
5
+
6
+ ## 当前需求理解 *
7
+
8
+ {{业务目标、主要场景、本次范围与明确不做的内容;未确认的理解标为待确认}}
9
+
10
+ ## 业务场景 *
11
+
12
+ | 场景编号 | 角色 | 前置条件 / 触发操作 | 预期业务结果 | 异常或边界处理 | 关联问题 |
13
+ |---|---|---|---|---|---|
14
+ | SC-1 | {{谁使用}} | {{在什么情况下做什么}} | {{用户能观察到的结果}} | {{业务上如何处理;无则写「无」}} | {{Q 编号;无则写「无」}} |
15
+
16
+ ## 待确认清单 *
17
+
18
+ | 编号 | 问题与场景 | 为什么要确认 / 影响 | 推荐答案与依据 | 产品 / 用户答复及来源 | 状态 |
19
+ |---|---|---|---|---|---|
20
+ | Q1 | {{关联 SC 场景,描述待定业务规则或范围;接口、表结构和实现选择留到 F3 / F4}} | {{影响的用户行为、范围或业务验收}} | {{用产品能理解的语言给建议及依据,不视为已确认}} | {{未答复 / 答复、来源与轮次}} | {{待确认 / 待 Qx 确认后讨论 / 已确认 / 已移出范围}} |
21
+
22
+ ## 本轮核对摘要 *
23
+
24
+ - 已确认:{{Q 编号及决定;无则写「无」}}
25
+ - 仍待确认:{{Q 编号,包括依赖前置答案的问题;无则写「无」}}
26
+ - 本轮新增:{{新增 Q 编号及原因;无则写「无」}}
27
+
28
+ ## 产品方案 / PRD 调整建议 *
29
+
30
+ {{按 Q 编号列出需补充或修改的业务规则、范围、验收描述;建议与已确认修改分开标明,无则写「无」}}
31
+
32
+ ## 当前验收标准草案 *
33
+
34
+ | 编号 | 场景 / 条件 | 预期行为 | 确认情况 / 关联问题 |
35
+ |---|---|---|---|
36
+ | AC-1 | {{输入或操作}} | {{可观察、可验证的结果}} | {{已确认 / 待 Qx 确认}} |
37
+
38
+ ## 反馈记录 *
39
+
40
+ - 第 {{1}} 轮:{{反馈来源、确认和变更的 Q 编号;尚无反馈则写「等待产品反馈」。后续追加,保留原决定变更记录}}
@@ -1,57 +1,61 @@
1
- # 需求澄清:分轮提问
1
+ # 业务场景清单与技术澄清
2
2
 
3
3
  <!-- 做法借鉴 grill-me(Matt Pocock 的 grill-me / grilling skills:https://github.com/mattpocock/skills),按开发需求的场景改写 -->
4
4
 
5
- 目标:动手前和用户对「要做成什么样」达成一致,不留下被默默假设的决定。返工最贵的情况是:代码写完了才发现边界、异常或兼容性理解错了。
5
+ 先与产品确认「用户在什么场景下要得到什么结果」,再结合现有系统澄清技术约束与影响。功能开发在 F2 输出业务清单,F3 做技术澄清;缺陷修复在 B3 内按先业务、后技术的顺序处理。
6
6
 
7
- ## 决策树
7
+ ## 事实自己查,决定交给用户
8
8
 
9
- 把需求拆成一棵决策树:每个决定下面挂着依赖它的决定。开发需求常见的分支:
9
+ - **事实**:PRD / DocNexus 已有规则、代码现状、接口、表结构和配置,自己查证,不拿能查到的事实反问用户;数据库按 `<skills>/workflow/references/tables.md` 只读核对。
10
+ - **决定**:产品规则、范围,以及会改变业务结果的技术取舍,给用户推荐答案和依据,等实际答复,不代替确认。
11
+ - 命名、分层和项目已有的实现惯例自己定;详细实现设计留在 F4。
10
12
 
11
- | 分支 | 典型问题 |
12
- |---|---|
13
- | 行为 | 正常路径的输入、输出、状态变化;谁会调用 |
14
- | 边界 | 空值、空列表、上下限、重复请求、时区、精度 |
15
- | 异常 | 下游失败、超时、数据不一致时返回什么、要不要重试 / 告警 |
16
- | 兼容 | 老客户端 / 老数据 / 已有调用方受不受影响;要不要开关灰度 |
17
- | 权限 | 谁能调、能看到谁的数据 |
18
- | 数据 | 要不要改表、迁移历史数据、保留多久 |
19
- | 范围 | 哪些明确不做、哪些留到下一期 |
13
+ ## F2 — 先落业务场景待确认清单
20
14
 
21
- 不是每个需求都有所有分支;只展开这个需求真正有的。
15
+ F1 形成初版需求理解后,在 F2、进入 F3 之前先输出清单,不必等技术问题全部查完。有未定业务场景或用户需要拿去与产品核对时,按 F4 标准初判规模并说明依据,选择完整流程,在首次落盘前 bind、start(stage F2,仅补记 Step0、F1,不能提前标 F2 completed)。读取 `resolve.mjs template dev clarification-template.md` 的生效模板,先写 tmp 草稿,再用 `artifact.mjs finalize --kind clarification` 发布到需求目录的 `clarification.md`,给用户文件链接。
22
16
 
23
- ## 事实自己查,决定交给用户
17
+ 清单聚焦产品能回答的问题:
24
18
 
25
- - **事实**:代码现在怎么做、表里有什么字段、配置怎么设、PRD / DocNexus 里写过什么、git 历史里为什么这样改——都自己查(读代码、`tables.mjs` 定位表、`database-query` 只读查表结构与索引(见 `<skills>/workflow/references/tables.md`)、`knowledge.mjs`、`git log -L`),不要问用户。
26
- - **决定**:业务规则、取舍、范围、上线方式——交给用户,每个问题都等用户回答,不要替用户回答。
27
- - 命名、分层、异常写法这类实现细节按项目既有写法自己定,不拿来问用户。
19
+ | 内容 | 核对重点 |
20
+ |---|---|
21
+ | 角色与目标 | 谁在用,要解决什么问题 |
22
+ | 正常场景 | 什么前置条件,做什么操作,预期看到什么结果 |
23
+ | 业务边界与异常 | 重复操作、取消、失败、无数据时业务上怎么办 |
24
+ | 业务规则 | 哪些人可做、哪些数据可见、状态如何变化 |
25
+ | 范围与验收 | 本次做什么、不做什么,怎样算完成 |
28
26
 
29
- ## 分轮提问
27
+ 接口字段、表结构、框架选择、重试机制等技术问题留到 F3 查证或 F4 设计;如果技术限制需要产品取舍,转换为对业务场景的影响再写入清单。只展开与本需求有关的场景,不穷举极端情况。
30
28
 
31
- **前沿**:前置决定都已经定下、现在就能问的问题。每一轮把整个前沿一次问完,编号,每个问题都给出你的**推荐答案**和依据(引用查到的代码 / 文档);然后等用户回答再进入下一轮。依赖本轮另一个问题答案的问题,留到下一轮。
29
+ 清单是正式流程产物,与 requirement.md、plan.md 同目录,纳入版本归档、文档视图和统计。发布清单不代表 F2 调研完成;等待产品反馈时保持 F2 in_progress,保存 status: waiting_user、waiting_for,以及 context 中的清单引用与待反馈事项。没有未定业务决定且用户未要求清单时,对话写「业务待确认项:无」,不额外落盘,后续沿用快速通道判定。
32
30
 
33
- ```
34
- ❓ **Q1 · <问题标题>**:<问题;有选项时列出选项>
31
+ ## 每轮怎样更新清单
35
32
 
36
- ➡️ 推荐:<你的推荐>。依据:<代码位置 / 文档 / 理由>
33
+ - 同一份清单维护最新状态:场景用 SC-1、SC-2…,问题用 Q1、Q2…;编号稳定,新场景 / 问题接着编号,保留已确认项,不整份重排。
34
+ - 每项写清场景、问题、业务影响、推荐答案与依据、产品 / 用户答复、状态;推荐只是建议,没有实际答复不能标已确认。
35
+ - 依赖前置答案的问题也记录,注明「待 Qx 确认后讨论」。每轮突出当前能确认的问题,控制在 7 个以内;用户说「按推荐来」只确认本轮已经给出的推荐。
36
+ - 用户带回答复或新版 PRD 后,恢复同一运行,从正式清单复制 tmp 草稿,更新原问题的答复和状态、追加新问题;反馈记录按轮追加。产品改口时保留原答复与变更原因。
37
+ - 每轮汇总「已确认 / 仍待确认 / 本轮新增」,给出 PRD 的业务规则、场景、范围和验收调整建议;只在用户要求修改 PRD 时改原文。
38
+ - 更新后再次 finalize,旧版自动归档,输出新版链接。内容变化会撤销本轮旧需求和方案凭据及下游确认,保留旧文件;后续须重新收尾需求与方案,M / L 重新确认方案。仍有未定业务项时继续留在 F2;「继续」或已修改 PRD 不代表未回答的问题自动确认。
39
+ - 新会话明确继续时,读清单、最新 PRD 和运行 context,从未解决项继续,不重问仍有效的已确认项。
37
40
 
38
- ---
41
+ 业务项均已回答或由用户明确移出范围后,将清单标为「业务已明确」并 finalize。结合核对后的场景完成 F2 的代码与数据调研,再 save F2 completed、进入 F3。这里不提前生成 requirement.md,也不把业务反馈视为技术约束已确认。
39
42
 
40
- ❓ **Q2 · <问题标题>**:…
43
+ ## F3 — 基于业务场景做技术澄清
41
44
 
42
- ➡️ 推荐:…
43
- ```
45
+ 以清单中的已确认场景(无清单时以已确认需求)和 F2 调研证据为输入,检查:
44
46
 
45
- - 每轮问题控制在 7 个以内;超过时先问对设计影响最大的。
46
- - 用户回答「按推荐来」→ 本轮所有推荐都算用户确认的决定。
47
- - 用户的回答改变了决策树(例如决定不做某个分支)→ 重新计算前沿,砍掉不再相关的问题。
48
- - 还在查的事实只挡住依赖它的问题;其余前沿问题照常问。
47
+ | 技术方向 | 自己查证 / 需要明确的约束 |
48
+ |---|---|
49
+ | 现有能力与可行性 | 系统能否支持目标场景,缺口在哪 |
50
+ | 接口与兼容 | 现有调用方、旧客户端与协议约束 |
51
+ | 数据与一致性 | 字段含义、已有数据、事务、迁移约束 |
52
+ | 权限与安全 | 现有鉴权与数据隔离能否满足业务规则 |
53
+ | 依赖与运行条件 | 下游能力、配置、性能容量及可验证条件 |
49
54
 
50
- ## 什么时候结束
55
+ 能查证的先查证;只有确实需要用户取舍的技术约束才分轮提问,给出推荐和依据,不把一般实现选择变成确认题。详细设计、改哪些文件和实施步骤留在 F4。
51
56
 
52
- 前沿为空时结束:决策树每个分支都走到了,没有被默默假设的决定。这时输出:
57
+ 技术调研发现新的业务决定或场景冲突时,回 F2 更新业务清单并等待产品确认;确认后重查受影响的技术事实,再回 F3。已确认且不受影响的场景不重复问。bug 在 B3 内更新清单后继续技术澄清。
53
58
 
54
- - **需求要点**、**验收标准**(可验证的行为)、**不在本次范围**
55
- - **已确认的决定**:每条一句话,标注是用户决定还是按推荐采纳
59
+ 业务场景与技术约束都明确后,汇总需求目标、范围、验收标准、已确认决定和必要技术约束。M / L 等用户确认理解一致;已有答复可直接复用,不重复确认。沿用已有运行、复核规模(无需清单时在此判定通道,完整流程 bind、start),用 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 并完成 F3 / B3,再进入 F4。
56
60
 
57
- M / L 规模等用户确认「理解一致」后,按 planning.md 的 F3 收尾先生成独立 requirement.md,再进入方案;这些决定保存在需求文档,plan.md 只引用需求路径与版本,交付说明按需汇总。值得长期记住的业务规则与取舍在交付时作为 DocNexus 沉淀候选。
61
+ requirement.md 是最终需求事实来源,引用清单 cite 与版本,只汇总有效场景、决定与约束;清单保留业务往返核对过程,plan.md 保存实现设计。值得长期记住的规则与取舍在交付时作为 DocNexus 沉淀候选。
@@ -46,5 +46,5 @@
46
46
  产物按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`,规则见 `<skills>/workflow/references/requirements.md`:
47
47
 
48
48
  - **需求名**:Step 0 已运行 `requirement.mjs which` 并问定名字。第一次落盘前运行 `requirement.mjs bind --name "<需求名>"`(用户明确同意按分支名生成时不带 `--name`);S 快速通道不 bind、不落盘。缺陷修复同样处理(可以选择挂到原需求下)。
49
- - **正式写入**:按 `<skills>/workflow/references/execution.md`,需求、方案、审查、交付都先写 tmp 草稿,再用 `artifact.mjs finalize --kind requirement|plan|review|delivery` 完成自检、旧版归档、索引与运行证据登记。缺陷修复在 B4 的方案草稿中保留原文并追加修复方案,不另建正式文件。
49
+ - **正式写入**:按 `<skills>/workflow/references/execution.md`,澄清清单、需求、方案、审查、交付都先写 tmp 草稿,再用 `artifact.mjs finalize --kind clarification|requirement|plan|review|delivery` 完成自检、旧版归档、索引与运行证据登记。缺陷修复在 B4 的方案草稿中保留原文并追加修复方案,不另建正式文件。
50
50
  - 使用输出的 path / cite 引用;previous 非空时告知上一版归档位置,不能替用户删除。中断先 `artifact.mjs resume --id <id>`,不能继续 sync / save 覆盖待办。独立文档仓库在交付完成后运行 pending,按 requirements.md 提示提交。已完成交付的 wiki/DocNexus 元信息更新仍显式 sync。
@@ -6,29 +6,29 @@
6
6
 
7
7
  - 需求来源是 PRD pageId/URL → 按 `prd-fetch.md` 拉取并提炼。
8
8
  - 先运行 `node <skills>/workflow/scripts/knowledge.mjs dev --match <模块名 / 业务名词> --query "<一句话需求>"`,看以往开发沉淀、技术方案和反复出现的审查问题里有没有相关的(`--query` 在这些分类内按正文 recall)。引用 `workflow-run/docnexus/library/<path>`(见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」)。
9
- - 先在心里列出初版 **需求要点 + 验收标准**(可验证的行为,而不是实现手段)和还没定的决定,带进 F2 查事实、F3 澄清。
9
+ - 先在心里列出初版 **需求要点 + 验收标准**(可验证的行为,而不是实现手段)和还没定的业务决定,带进 F2 先出业务场景清单,再查技术事实、进入 F3 技术澄清。
10
10
 
11
- ### F2 — 现状调研
11
+ ### F2 — 业务场景核对与现状调研
12
+
13
+ 先读 `clarify.md` 的 F2:基于 F1 的需求理解,先落偏业务场景的 clarification.md,供用户与产品核对角色、正常 / 异常场景、规则、范围与业务验收,不等到 F3 才输出。需要清单时初判规模、选择完整流程,bind、start(stage F2,仅补记 Step0、F1),按模板写 tmp 草稿并 `artifact.mjs finalize --kind clarification`;逐轮更新问题状态、追加新问题与反馈记录,等待时 F2 in_progress、运行为 waiting_user。业务明确后发布最终清单,结合场景完成以下调研,再记录 F2 completed、进入 F3。无需清单时在对话写明业务待确认项为无,直接调研。
12
14
 
13
15
  - 从入口(Controller / Handler / CLI / 页面)沿调用链读到持久层,理清数据流;不凭文件名猜内容。按本轮 CodeGraph 通道先用 `codegraph_explore` / `codegraph explore "<问题>"` 一次拿到链路上的源码和调用路径,再按需补读;Spring 注入、MyBatis XML、MQ、配置 key 这些图谱看不到的照常 grep(见 `<skills>/workflow/references/codegraph.md`)。
14
16
  - 找到同类功能的既有实现,作为风格与结构的参照(命名、分层、异常、日志、事务、DTO 转换方式)。
15
17
  - 涉及数据库 → 按 `<skills>/workflow/references/tables.md` 先确定涉及哪些表(`tables.mjs --files <读到的实体 / Mapper>`),按本轮数据库通道用 `query.mjs --schema --tables <表> --indexes` 只读拉取实际字段、索引与行数;方案里的字段名、类型、索引和 DDL 以查到的为准,不凭实体类推测。
16
18
 
17
- ### F3 — 需求澄清
19
+ ### F3 — 需求澄清(偏技术约束)
18
20
 
19
- 按 `clarify.md` 分轮提问:把需求拆成决策树(行为、边界、异常、兼容、权限、数据、范围),**事实自己查**(代码、表结构、PRD、DocNexus),**决定交给用户**;每轮把现在就能问的问题一次问完,编号并给出推荐答案和依据,等用户回答后再问下一轮,直到没有被默默假设的决定。
21
+ 读 `clarify.md` 的 F3,以已确认业务场景和 F2 证据为输入,查清现有能力、接口兼容、数据与一致性、权限、依赖、性能和可验证条件。事实自己查;需要用户取舍的约束给出推荐与依据,按轮确认。命名、分层等既有实现惯例自行遵循,详细设计留到 F4。技术问题影响业务场景时回 F2 更新清单、找产品核对,不在技术澄清里默默改业务规则。
20
22
 
21
23
  | 情况 | 做法 |
22
24
  |---|---|
23
- | S 规模且 F2 后没有未定的决定 | 跳过需求澄清提问,写明本次的理解和假设;F3 收尾按 F4 标准判定规模并告知用户 |
24
- | 只有一两个小决定 | 问一轮即可 |
25
- | M / L 规模,或用户说「拷问一下 / grill me / 先把需求问清楚」 | 按轮问到前沿为空,输出需求要点、验收标准、不在本次范围、已确认的决定,**等用户确认理解一致**再进 F4 |
26
-
27
- 不要边写代码边问:实现中才发现的新决定,停下来按同样格式问,再继续。
25
+ | S 规模且没有未定业务或技术决定 | 写明理解与已查证约束,不强行提问;按 F4 标准判规模与通道 |
26
+ | 只有一两个技术取舍 | 给推荐和依据,能一轮确认就一轮结束 |
27
+ | M / L 规模,或用户要求先把需求问清楚 | 逐轮确认约束,汇总需求、AC、不做什么与决定,等用户确认理解一致再进 F4 |
28
28
 
29
- **澄清后的首个产物**:先按下文 F4 标准判定规模并决定是否走快速通道,已有答复直接复用,不再问一次。完整流程在此绑定需求、创建 feature 运行(stage F3,仅补记 Step0、F1、F2),用 `resolve.mjs template dev requirement-template.md` 取生效模板,将目标、范围、不做什么、验收标准(AC 编号)、已确认决定与剩余问题写到独立草稿。通过 `artifact.mjs finalize --kind requirement` 收尾为 `requirement.md` 并将 F3 标 completed,再进入 F4。M / L 仍按上表先确认理解一致,不新增一轮重复确认;阻止实现的业务决定未明确时停在 F3。
29
+ **F3 的正式产物**:业务与技术约束均明确后,沿用已有绑定和运行、复核规模;没有清单时,完整流程在此 bind、start(stage F3,仅补记实际完成的 Step0、F1、F2)。用 `resolve.mjs template dev requirement-template.md` 读取模板,将目标、范围、AC、当前有效业务决定与必要技术约束写成草稿,在依据中引用业务清单 cite 与版本。通过 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 并将 F3 标 completed,再进入 F4。不因清单发布或产品给了业务答复就跳过技术澄清。
30
30
 
31
- `requirement.md` 是需求事实来源,`context` 只保存续接摘要,不单独维护另一套验收。方案、验证和审查引用该文档的版本与 AC 编号。需求变化时回 F3 更新、重新收尾,再根据新版本更新方案并重新确认 / 验证;仅调整实现方案不改需求文档。历史需求不会自动从旧 plan.md 拆出正文;恢复旧开发运行需要先核实并补齐需求文档。
31
+ requirement.md 是需求事实来源,context 只保存续接摘要。业务变化先回 F2 更新清单、复核现状,再到 F3 更新需求文档;仅技术约束变化回 F3;只调整实现设计则更新 F4 的方案。需求重新收尾后,更新依赖它的方案并重新确认 / 验证。历史需求不自动从旧 plan.md 拆出正文;恢复旧运行时先核实并补齐需求文档。
32
32
 
33
33
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
34
34
 
@@ -40,10 +40,10 @@
40
40
 
41
41
  规模拿不准时按大一级处理。涉及权限(鉴权、角色、数据可见范围)或资金(金额计算、扣款、退款、对账)的改动,文件再少也至少按 M:需求理解(F3)和方案都要用户确认。
42
42
 
43
- **规模判定(S / M / L 都必做,不再询问用户)**:规模由你按上表判定,向用户说明判定的规模与依据(预计改动文件 / 模块、接口 / 数据 / 配置变化及风险)即可,**不询问、不等确认**,直接按该规模推进后续流程;用户主动提出不同意见时,按用户说的规模继续。用户调整范围或实现中发现规模变化时,说明变化依据,按新规模继续。规模判定属于流程选择,不算 F3 的业务决定,不影响 S 规模快速通道资格。
43
+ **规模判定(S / M / L 都必做,不再询问用户)**:规模由你按上表判定,向用户说明判定的规模与依据(预计改动文件 / 模块、接口 / 数据 / 配置变化及风险)即可,**不询问、不等确认**,直接按该规模推进后续流程;用户主动提出不同意见时,按用户说的规模继续。用户调整范围或实现中发现规模变化时,说明变化依据,按新规模继续。规模判定属于流程选择,不属于业务决定,不影响 S 规模快速通道资格。
44
44
 
45
45
  **需求绑定与方案依据**:完整流程已在 F3 收尾前绑定并生成 requirement.md,本步直接沿用;方案头写需求文档的 cite 与版本,需求目标、范围和业务决定不复制到方案中维护。方案只解释如何实现,并用 AC 编号关联验证计划。S 快速通道不绑定。
46
46
 
47
- **S 规模快速通道(问用户)**:判定为 S 规模,且改动**不涉及**配置项、SQL / DDL、对外接口(HTTP 接口签名、MQ 消息体、对外 DTO)、表结构、权限、资金,也没有 F3 中确认过的业务决定时,**明确询问用户是否走快速通道**:说明走快速通道时 F5~F6 照常(编译、测试都不省),审查按 F7 的快速通道说明在当前会话做,但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写(运行反馈仍照常记一行),F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续:明确同意才走快速通道;拒绝或答复没有明确同意,就按完整流程落盘交付(F3 需求 → F4 方案 → F7 审查 → F8 交付)。** 实现中一旦碰到上面任何一项、改动超过 3 个文件,或用户要求落盘 → 退出快速通道:先停下后续实现,重新评估并说明规模,按 Artifact Location 绑定需求,先回 F3(缺陷回 B3)补写并 finalize requirement.md,再到 F4 / B4 补方案;M / L 等用户确认方案后再继续,S 按简版方案推进。之后回 F5 完成实现、F6 验证、F7 审查并生成 `review.md`,交报告后等待用户选择交付,不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问,不省审查。
47
+ **S 规模快速通道(问用户)**:本次已发布正式清单或已创建完整流程运行时,直接沿用完整流程,不再询问快速通道;后续规模降为 S 也不切换。判定为 S 规模,且改动**不涉及**配置项、SQL / DDL、对外接口(HTTP 接口签名、MQ 消息体、对外 DTO)、表结构、权限、资金,也没有 F2 / F3 中确认过的业务决定,且本次尚未发布正式清单、尚未创建完整流程运行时,**明确询问用户是否走快速通道**:说明走快速通道时 F5~F6 照常(编译、测试都不省),审查按 F7 的快速通道说明在当前会话做,但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写(运行反馈仍照常记一行),F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续:明确同意才走快速通道;拒绝或答复没有明确同意,就按完整流程落盘交付(F3 需求 → F4 方案 → F7 审查 → F8 交付)。** 实现中一旦碰到上面任何一项、改动超过 3 个文件,或用户要求落盘 → 退出快速通道:先停下后续实现,重新评估并说明规模,按 Artifact Location 绑定需求,先回 F3(缺陷回 B3)补写并 finalize requirement.md,再到 F4 / B4 补方案;M / L 等用户确认方案后再继续,S 按简版方案推进。之后回 F5 完成实现、F6 验证、F7 审查并生成 `review.md`,交报告后等待用户选择交付,不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问,不省审查。
48
48
 
49
- **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。方案草稿通过 `<skills>/workflow/references/execution.md` 的 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 等用户确认并 save approval 后再进入 F5,S 无需 approval(方案按简版写)。S 先按上面的快速通道问一次:同意则不写方案,不同意或未明确同意才落盘。
49
+ **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。方案草稿通过 `<skills>/workflow/references/execution.md` 的 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 等用户确认并 save approval 后再进入 F5,S 无需 approval(方案按简版写)。尚未创建本次完整流程运行、且符合快速通道全部条件的 S,按上文询问一次;已经发布清单或创建运行的 S 直接落简版方案,不重复询问快速通道。
@@ -6,7 +6,7 @@
6
6
 
7
7
  按 `<skills>/workflow/references/runs.md` 保存和恢复进度,状态统一在需求的 `meta.json`,不另建状态文件。确定工作分支后先 `run.mjs show`;有 pending_finalization 先按 execution.md 恢复/取消收尾,用户要求继续时读取对应运行的 context、已完成步骤与等待事项,核对代码和证据后从保存的阶段恢复,不重走有效的已完成步骤。不能把“继续”当成用户选择交付。
8
8
 
9
- 新任务在 F3 / B3 收尾确定不走快速通道后,先绑定需求,再 `run.mjs start --kind feature|bug --size <规模> --input <checkpoint.json>`,把前置步骤、需求摘要与基线补入 checkpoint。功能开发从 F3 创建(仅补记 Step0、F1、F2),缺陷修复从 B3 创建(仅补记 Step0、B1、B2);先 finalize requirement.md 再完成 F3 / B3、进入方案。快速通道不 start、不 save。
9
+ 新任务需要业务清单时,先按 F4 标准初判规模并选择完整流程,bind、start(feature stage F2,仅补记 Step0、F1),在 F3 前发布 clarification.md;等待产品反馈时保持 F2 in_progress、运行为 waiting_user。业务明确并完成 F2 调研后进入 F3 技术澄清。无需清单时,完整流程在 F3 收尾需求前 bind、start,仅补记真实完成的 Step0、F1、F2。bug 从 B3 创建,仅补记 Step0、B1、B2,在 B3 内先核对业务再澄清技术。业务与技术约束均明确后才 finalize requirement.md 并完成 F3 / B3。快速通道不 start、不 save。
10
10
 
11
11
  每个步骤完成、等待用户、遇到阻塞和结束本轮会话前 save,明确标记步骤 completed 并记录证据。方案待确认时运行为 waiting_user;F7 报告交给用户后也保存 waiting_user 和“修复或交付”,不能仅因报告存在就继续。用户选修复时记录确认的 fix 并回 F5(bug 回 B4),自动重置后续完成标记;选交付时记录确认的 deliver 并进 F8(bug 留 B5)。规模变化同时更新 size。
12
12
 
@@ -25,8 +25,8 @@
25
25
 
26
26
  ## 待确认问题 *
27
27
 
28
- {{剩余未定问题及对范围的影响;全部澄清后写「无」。阻止实现的决定未明确时不进入方案阶段}}
28
+ {{业务与技术约束全部澄清后写「无」;还有业务决定时回 F2 更新业务清单,技术约束未明确时留在 F3,不收尾进入方案阶段}}
29
29
 
30
30
  ## 事实与依据(如有)
31
31
 
32
- {{PRD、代码、数据或远程配置的来源;缺陷修复附复现与根因证据,不在这里写实现方案或测试执行结果}}
32
+ {{PRD、代码、数据或远程配置的来源;有澄清清单时引用 clarification.md 的 cite 与版本,核对过程保留在清单中;缺陷修复附复现与根因证据,不在这里写实现方案或测试执行结果}}
package/dev/skill.json CHANGED
@@ -39,6 +39,12 @@
39
39
  "对比分支"
40
40
  ]
41
41
  }
42
+ },
43
+ {
44
+ "id": "clarification-template.md",
45
+ "src": "references/clarification-template.md",
46
+ "title": "业务场景待确认清单模板",
47
+ "summary": "F2 / B3 在技术澄清前供产品核对的正式业务场景清单,与需求文档同目录,按版本记录答复、新增问题及 PRD 调整建议,需求明确后再收尾需求文档。"
42
48
  }
43
49
  ],
44
50
  "shared": [