@nathan33/nao-skill 0.16.2 → 0.17.0

package/.agents/checklists/deliverable-docs.md

@@ -14,7 +14,7 @@ description: 交付文档写作规范（PRD/ADR/报告/调研：简洁、可读
 3. **写决策不写过程，写差异不复述**：与代码 / 上游文档重复的内容一律用指针（`路径#小节`）。
 4. **超预算就删，不是加长**：每份文档有长度上限；超了先删「常识 / 过程 / 全量罗列」，仍超才另附文件。
 
-- **PRD**：上限 ≤150 行；必须留下 9 模块结论、范围/非范围、AC；禁止 抄竞品原文、贴代码。
+- **PRD**：上限 ≤150 行；必须留下 9 模块结论、范围/非范围、AC；禁止 抄竞品原文、贴代码；**非范围必带理由**。模板见 `@.agents/templates/prd.md.example`。
 - **ADR**：上限 ≤60 行；必须留下 决策、对照模式、参考来源；禁止 大段代码、教程式背景。
 - **评审报告**：上限 ≤60 行；必须留下 可行性、风险、取舍、待拍板点；禁止 复述 PRD。
 - **测试报告**：上限 ≤80 行；必须留下 范围、结果数字、缺陷、风险、建议；禁止 日志/截图全文。
@@ -44,6 +44,7 @@ description: 交付文档写作规范（PRD/ADR/报告/调研：简洁、可读
 
 - 首屏 TL;DR（≤5 行）：做什么 · 给谁 · 成功标准 · 不做什么
 - 9 模块：**每模块一小节**，内容用列表承载（**不用表格**）；每项 **≤3 句 / ≤60 字**；不适用项写「不适用：<一行理由>」，**不许留空、不许写废话**
+- **非范围必带理由**：每条非范围后跟一行理由（即写「不适用」也要给理由），否则视为未完成
 - AC 逐条 Given/When/Then，一条一行
 - 推演细节（RICE 打分过程、5 Whys 展开、同类产品调研明细）落 `docs/research/` 或附录，**正文只留结论 + 指针**
 - **⛔ PRD 正文不使用表格** ⇒ 改用**有序 / 无序列表 + 加粗字段名**（如 `- **版本**：1.12.3`）。最常被误写成表格的三处：**需求清单（用户故事 / 条目）· 验收标准（AC）· 范围 / 非范围**。

package/.agents/checklists/pm.md

@@ -61,12 +61,14 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 - [ ] release notes 不可读（纯编号/类名/路径），或未落盘 `docs/releases/`？（规范：@.agents/common/release-notes.md —— 面向用户「本次更新」置顶、内部信息下沉、正文不用表格）
 - [ ] 降级（无 `gh` / 无远端）未在 `tasks-state` 与回执中标注？
 
-## 交付检查清单（完整 36 项）
+## 交付检查清单（完整 38 项）
 
 - [ ] 目标/边界/验收三件事齐备
 - [ ] 证据 + 5 Whys 已产出
 - [ ] 战略筛子已过，RICE 可追溯
 - [ ] PRD 含 9 模块
+- [ ] 接缝候选已列并经 qa 确认（不适用注明理由）
+- [ ] 路径无关判据已核（@.agents/skills/pm-to-spec.md §六 逐条）
 - [ ] 场景模块含画像+场景卡+关键路径+页面状态清单
 - [ ] AC 五覆盖
 - [ ] 变更记录完整（含 Hotfix）

package/.agents/checklists/qa.md

@@ -24,12 +24,13 @@ description: 测试工程师交付核对清单（按需，交付前读取）
 - [ ] 视觉/UI 呈现类验证启动了浏览器自动化（无头浏览器/截图对比）？（应产出用户验收清单交用户人工，见 skills/test-design.md「视觉/UI 呈现验证」）
 - [ ] 含 UI 呈现的交付未产出用户验收清单（测什么/怎么操作/预期结果/对应 AC）？
 
-## 交付检查清单（完整 17 项）
+## 交付检查清单（完整 18 项）
 
 - [ ] 测试计划含范围与风险评估（测什么/不测什么）
 - [ ] 未私自修改现有功能代码
 - [ ] 执行前已列清单并经**用户/PM（开工确认卡）**确认范围
 - [ ] 用例覆盖等价类/边界/主路径/异常，且可追溯 AC
+- [ ] 接缝确认已作为 PRD 阶段输入：PM 列候选 → QA 确认/修正 → 写入 PRD「AC」首行，用例按确认后的接缝组织
 - [ ] 分层测试与 DDD 分层对齐
 - [ ] 缺陷全量入库、信息完整、生命周期闭环
 - [ ] 回归已执行（冒烟 + 受影响），未过未放行

package/.agents/prompts/product-manager.md

@@ -1,8 +1,8 @@
 ---
 description: 产品经理角色 Prompt（短常驻）——需求分析/PRD/优先级/验收/多会话调度
 role: pm
-version: 23
-updated: 2026-10-13
+version: 24
+updated: 2026-10-14
 ---
 
 # 产品经理（PM）
@@ -10,6 +10,7 @@ updated: 2026-10-13
 > 通用规范见 @.agents/common/output-format.md 与 @.agents/common/intercom-protocol.md（常驻）。
 > 项目上下文：项目根 `AGENTS.md`（项目级属性/约束，PM 维护，pi 自动加载，见 §七）。
 > 按需技能：@.agents/skills/pm-rice.md（优先级）、@.agents/skills/pm-grill.md（澄清）。
+> @.agents/skills/pm-to-spec.md（成熟需求直出 PRD：验证接缝 + 对话综合；判定命中即跳过 grill）。
 > @.agents/skills/pm-routing.md（路由与派单纪律 + 技术调研边界；派发/调研前读取）。
 > @.agents/skills/pm-operations.md（调度细则 / 开工确认卡 / 会话生命周期 / AGENTS.md 治理 / 归档）。
 > @.agents/skills/codegraph.md（验收读码：node --file/--limit 行段读取，禁 cat 全文）。
@@ -31,6 +32,7 @@ updated: 2026-10-13
 
 9 模块：**问题证据｜目标指标｜范围/非范围｜用户场景｜业务规则｜NFRs｜AC｜上线闭环｜变更治理**。
 9 模块是验收闸门不得删；**正文用列表 + 加粗字段名承载，不用表格**（写法规格见 @.agents/checklists/deliverable-docs.md §三）。
+**入口分支**：需求成熟（命中 @.agents/skills/pm-to-spec.md 判定）→ 接缝 + 对话综合直接成稿；不成熟 → 先走 grill 五层追问。
 每模块内容与缺失后果速查（**写前参考，非正文格式**）：@.agents/checklists/pm.md（写 PRD 前读取）。
 
 ## 三、需求工作流（七阶段）

package/.agents/prompts/test-engineer.md

@@ -1,8 +1,8 @@
 ---
 description: 测试工程师角色 Prompt（短常驻）——策略/用例/缺陷/质量保障
 role: qa
-version: 13
-updated: 2026-10-13
+version: 14
+updated: 2026-10-14
 ---
 
 # 测试工程师（QA）
@@ -62,6 +62,7 @@ DDD 分层对齐（简）：
 - **AC = 测试用例**：Given/When/Then 直接转译；无 AC 需求先补齐再测。
 - **业务规则 → 领域测试**：状态流转、不变量对应 domain 单测；发现规则散落组件/Service 时提示研发收敛。
 - **评审参与**：需求评审确认可测性（数据口径/埋点/边界）。
+- **接缝确认 = QA 在 PRD 阶段的输入**：PM 列验证接缝候选（理想 1 个、优先复用、能高不高低）→ QA 确认或修正（可改为更高/更少）→ PM 写入 PRD「AC」首行；用例按确认后的接缝组织（流程见 @.agents/skills/pm-to-spec.md，用例设计见 @.agents/skills/test-design.md）。
 - **缺陷闭环联动**：指派明确、信息完整，避免"环境问题/数据问题"推诿。缺陷**全量入库**，落点见 @.agents/skills/test-design.md「缺陷管理」（`docs/reports/<编号>-defects.md` 或项目约定缺陷平台）。
 - **PR 验证**：在 PR 评论贴**全量门禁精确数字**（命令 + exit code + 文件数/例数/红数）与预览环境结论；**PM 验收通过前不得以"测试已过"为由催促合并**（合并由 RD 在 PM 授权后执行）。
 

package/.agents/skills/pm-grill.md

@@ -6,6 +6,10 @@ description: 按需技能——苏格拉底式澄清（grill-me）
 
 需求模糊时**必须**触发，逐层追问直至澄清，澄清前不得写 PRD。
 
+## 需求成熟度判定：命中则不触发
+
+先按 @.agents/skills/pm-to-spec.md §一 判成熟度（① 已有 grill 结论；② 已有原型/设计稿；③ 已有 ADR 或架构评审回执；④ 用户明示「讨论已充分」）。**任一命中 → 不触发本清单**，改走该技能的对话综合流程；一条都不命中才逐层追问。判定与综合入口口径以 `pm-to-spec.md` 为准，本文件不另设标准。
+
 ## 五层追问
 
 1. **目标用户**：谁？画像？规模？

package/.agents/skills/pm-to-spec.md

@@ -0,0 +1,83 @@
+---
+description: 按需技能——成熟需求的规格生产方式（验证接缝 + 对话综合，产出仍为 PRD）
+---
+
+# pm-to-spec（成熟需求直出 PRD）
+
+> 入口分支：需求**已成熟**（命中 §一 判定）时跳过 grill，走「接缝 → 综合 → 缺口检查 → 出稿」；不成熟仍走 @.agents/skills/pm-grill.md 五层追问。
+> 产出物一律叫 **PRD**（禁 `spec` 作并列术语）；格式 = 头部 + TL;DR + 9 模块（见 @.agents/checklists/deliverable-docs.md §三）。
+
+## 一、成熟度判定（4 条，任一命中即可走综合）
+
+1. **已有 grill 结论**：本需求已跑完五层追问并澄清。
+2. **已有原型 / 设计稿**：用户或 RD 已给出界面 / 交互稿。
+3. **已有 ADR 或架构评审回执**：`docs/adr/` 或 arch 回执已定关键取舍。
+4. **用户明示「讨论已充分」**：用户显式表示可直接成稿。
+
+- **一条都不命中 → 仍走 grill**，不得跳过；命中后也只在缺口处定点补产，不重复盘问。
+- 判定结论写入 PRD 头部指针（来源：grill 结论 / 原型 / ADR），供回执核对。
+
+## 二、接缝步骤（写 PRD 前先定可测接入点）
+
+- **PM 列候选 → QA 确认**：PM 只列 1–3 个候选接入点；最终以 QA 确认为准（QA 可改为更高 / 更少）。
+- **理想 1 个接缝**：接缝越少越好。
+- **优先复用已有接缝**：已有测试 / 调用入口优先于新建。
+- **能高不高低**：能在高层稳定接口测，就不下沉到实现细节。
+- 结论写入 PRD「七、AC」首行：`验证接缝：<接入点>（QA 已确认 YYYY-MM-DD）`；不适用写「不适用：<一行理由>」。
+- **一致性闸门（AC8）**：PRD 接缝与 QA 用例范围不一致 → PM 验收**打回**，对齐后重新验收（不得带不一致合入）。
+
+## 三、对话综合流程
+
+1. **判成熟度**（§一）：不命中 → 回 grill。
+2. **列接缝候选 → 请 QA 确认**（§二）。
+3. **综合上下文成稿**：按 §四 映射把已有讨论填进 9 模块；只综合已知，不重新盘问。
+4. **缺口检查**（§五）：缺口未清空不得出稿。
+5. **自核路径无关判据**（§六）→ 落 `docs/prds/` + 更新索引。
+
+## 四、上游 7 节 → 9 模块映射（列表，非表格）
+
+上游 `to-spec` 模板 7 节按下述归位；**实现决策 / 测试决策不落 PRD 正文**，只留指针：
+
+1. **问题证据** ← 上游「问题陈述」。
+2. **目标指标** ← 上游无对应：取 5 Whys + 北极星拆解；无依据即记缺口（§五）。
+3. **范围/非范围** ← 上游「用户故事」+「范围外」（非范围必带理由）。
+4. **用户场景** ← 上游「解决方案」（能力 / 关键路径视角）。
+5. **业务规则** ← 上游「解决方案」+「补充说明」中的状态 / 权限 / 边界 / 不变量。
+6. **NFRs** ← 上游「补充说明」的业务视角基线；无则写「不适用：<理由>」。
+7. **AC** ← 上游「用户故事」逐条转 Given/When/Then；首行为验证接缝（§二）。
+8. **上线闭环** ← 上游「补充说明」（灰度 / 监控 / 回滚）；缺则按项目默认并记缺口。
+9. **变更治理** ← 上游「补充说明」（正式流程 + 版本记录）。
+- **上游「实现决策」** → ⛔ 不写正文，指针 `docs/adr/`。
+- **上游「测试决策」** → ⛔ 不写正文，指针 QA 用例范围（`docs/reports/`）。
+
+## 五、缺口检查（缺口未清空不得出稿）
+
+逐条核对，缺一即列缺口并定点补产（补产靠 grill / 原型 / ADR / 用户拍板）：
+
+- 目标指标（北极星拆解 + 预期值）
+- NFRs（性能 / 安全 / 兼容性业务基线）
+- 上线闭环（灰度 / 监控 / 回滚）
+- 变更治理（正式流程 + 版本记录）
+
+处理顺序：先输出**缺口清单**（编号 + 缺口 + 影响）→ 定点补齐 → 复检清空 → 才可出稿。**不得**带着缺口直接成稿。
+
+## 六、路径无关判据清单（AC1，第三方逐条可核）
+
+- 头部齐（状态 / 更新 / Owner / 指针）
+- TL;DR ≤5 行（做什么 · 给谁 · 成功标准 · 不做什么）
+- 9 模块无空（不适用项写「不适用：<理由>」）
+- AC 逐条 Given/When/Then + 五覆盖（主路径 / 异常 / 边界 / 负向闭环 / 设计一致性）
+- 非范围含理由
+- 战略筛子 + RICE 结论在
+- 正文无表格
+- ≤150 行
+- 落 `docs/prds/` 且索引更新
+- Issue 只有摘要 + 指针（正文在 `docs/prds/`）
+
+> 判据与 @.agents/checklists/deliverable-docs.md §三、@.agents/checklists/pm.md 一致；模板见 @.agents/templates/prd.md.example。
+
+## 反模式
+
+- 不判成熟度就直接盘问（重复澄清轮次）。
+- 接缝由 PM 单方拍定、未经 QA 确认。
+- 带缺口出稿；写「实现决策 / 测试决策」正文；用 `spec` 作并列术语或替代 PRD 直发 tracker。

package/.agents/templates/prd.md.example

@@ -0,0 +1,65 @@
+<!--
+  PRD 骨架 —— 复制为 docs/prds/YYYY-MM-DD-<slug>.md 后逐段填空。
+  权威写法：@.agents/checklists/deliverable-docs.md §三；生产方式：@.agents/skills/pm-to-spec.md
+  ⛔ 自查：正文无表格；每模块 ≤3 句；不适用项写「不适用：<理由>」；AC 一条一行；≤150 行。
+-->
+
+# PRD：<标题>
+
+- 状态：草稿 / 待确认 / 已定稿 · Owner：PM
+- 更新：YYYY-MM-DD
+- 指针：上游 <Issue / 讨论> · 关联 ADR / 调研 `docs/...md`
+- 优先级：<战略筛子结论 / RICE 高|中|低>
+
+## TL;DR（≤5 行）
+
+- **做什么**：<一句话>
+- **给谁**：<用户 / 角色>
+- **成功标准**：<可核指标>
+- **不做什么**：<边界>
+
+## 一、问题证据
+
+<数据 / 反馈 + 5 Whys 摘要（展开落 `docs/research/`）>
+
+## 二、目标指标
+
+<北极星拆解 + 预期提升值>
+
+## 三、范围 / 非范围
+
+- **范围**：<条目>
+- **非范围**：<条目 + 一行理由>
+
+## 四、用户场景
+
+<画像 + 场景卡 + 关键路径 + 页面状态清单（加载 / 空 / 错误 / 成功）>
+
+## 五、业务规则
+
+<状态流转 / 权限 / 边界 / 不变量>
+
+## 六、NFRs
+
+<性能 / 安全 / 兼容性业务基线；不适用：<理由>>
+
+## 七、AC
+
+- 验证接缝：<接入点>（QA 已确认 YYYY-MM-DD）
+- AC1（主路径）：Given <前置>，When <操作>，Then <预期>
+- AC2（异常）：Given <前置>，When <操作>，Then <预期>
+- AC3（边界）：Given <前置>，When <操作>，Then <预期>
+- AC4（负向闭环）：Given <前置>，When <操作>，Then <预期>
+- AC5（设计一致性）：Given <前置>，When <操作>，Then <预期>
+
+## 八、上线闭环
+
+<灰度 / 监控 / 回滚>
+
+## 九、变更治理
+
+<正式流程 + 版本记录（Hotfix 24h 补单）>
+
+## 附录：战略筛子 / RICE 结论
+
+<结论 + 指针；打分过程不展开>

package/README.md

@@ -24,7 +24,7 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 
    ```bash
    cd 你的项目
-   pi install --local npm:@nathan33/nao-skill@0.16.2   # 声明 pin + 把机制包物化到项目内 .pi/npm
+   pi install --local npm:@nathan33/nao-skill@0.17.0   # 声明 pin + 把机制包物化到项目内 .pi/npm
    npx @nathan33/nao-skill init                        # 写入转发 shim + 生成 AGENTS.md
    ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathan33/nao-skill",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
   "type": "module",
   "bin": {