@prd-improve/cli 1.0.0 → 1.1.0

package/dist/skill/prd-improve-forge/SKILL.md

@@ -0,0 +1,610 @@
+---
+name: prd-improve-forge
+description: Use when user wants to write, refine, or structure a PRD for a specific feature — converting vague ideas, meeting notes, chat snippets, or legacy docs into a complete, edge-specified spec following PRD Improve schema v0.2. Differentiator from generic PRD helpers — drives multi-round boundary questioning (P0/P1/P2 priorities) via feature-type checklists and outputs structured `.prd/features/<slug>/working/prd.yaml` (not free-form Markdown), so downstream `prd validate` / `prd freeze` / `prd context` CLI commands can consume it. Triggers on Chinese phrases like '写 PRD'、'整理需求'、'规范化需求'、'把 X 整理成 PRD'、'梳理功能边界'、'会议纪要整理成需求'、'聊天记录整理成 PRD'、'把这个想法变成规格'、'帮我做需求规格化' or English equivalents. DO NOT trigger for: (a) general product strategy / OKR / roadmap discussion without a specific feature scope; (b) writing code, implementation, architecture, or technical design docs; (c) editing a single field of an already-frozen PRD (use `prd` CLI directly); (d) high-level vision documents or pitch decks. Also triggers on PRD refresh requests — when an existing .prd/features/<slug>/working/prd.yaml needs to be updated against a new PRD version. Refresh triggers '同步新版 PRD'、'重新 sync'、'基于新版 PRD 更新'、'PRD 改了'、'PRD 升级了'、'feature 升级'、'对齐 PRD'、'incorporate PRD changes' or equivalents. Skill loads existing yaml + new PRD, runs structured field-level diff via `prd refresh`, walks PM through decisions, writes patches + appends working/CHANGELOG.md. DO NOT trigger refresh for PRD 大改 / 几乎重写(→ 重跑白板模式);单字段修订(→ 直接 edit yaml 或 prd CLI);现有 yaml 不存在(→ 自动 fallback 白板模式).
+---
+
+# PRD Improve Forge
+
+把一个功能从**模糊想法**推进到**可开发、可测试、可追溯**的结构化 PRD。
+产出文件符合 PRD Improve schema v0.2,可直接被 `prd validate` / `prd freeze` / `prd context` 等 CLI 命令消费。
+
+## 适用与不适用
+
+**适用:**
+- 有一个**具体功能**要写成 PRD(如"批量导入"、"审批流"、"权限管理")
+- 已有原始材料(会议纪要、聊天片段、旧 PRD、AI 对话)要整理成规范
+- 把一句话需求扩展成完整规格
+
+**不适用:**
+- 产品战略 / OKR / 路线图 —— 本 Skill 不做
+- README / 技术设计文档 / 架构文档 —— 本 Skill 不做
+- 没有明确功能边界的模糊讨论 —— 先引导用户聚焦到具体功能再触发
+
+---
+
+## 工作流程(严格按顺序执行)
+
+### 第 1 步:识别模式 + 功能类型
+
+#### 1.1 识别模式(白板 vs refresh)
+
+按以下顺序判定:
+
+1. **触发词 ∈ refresh 集合 + `working/prd.yaml` 存在** → refresh 模式 → 跳第 7 步
+2. **触发词 ∈ refresh 集合 + `working/prd.yaml` 不存在** →
+   询问用户「未找到现有 yaml,确认要走白板模式从 0 生成吗?」
+   默认 fallback 白板 + 明确告知
+3. **其他触发词** → 白板模式 → 走 1.2
+
+**refresh 触发词集合**(5 类信号):
+
+| 类型 | 中文 | 英文 |
+|---|---|---|
+| 变化 | "PRD 改了" / "PRD 变了" / "PRD 升级了" / "PRD 迭代" / "PRD 出了新版" / "新版 PRD 已经发了" | "PRD changed" / "PRD updated" / "new PRD version" |
+| 同步 | "重新 sync" / "同步新版 PRD" / "把 PRD 同步到 yaml" / "刷新 PRD" / "重新刷一遍 PRD" | "resync PRD" / "refresh PRD" / "sync yaml with PRD" |
+| 更新 | "基于新版 PRD 更新" / "按新版调整 yaml" / "更新已有 PRD" / "feature 升级" | "update from new PRD" / "update yaml to new PRD" |
+| 对齐 | "重新对齐 PRD" / "yaml 跟最新 PRD 对齐" / "把 yaml 和 PRD 对齐" | "align yaml with new PRD" |
+| 吸收 | "把这版 PRD 的变化吃进来" / "增量更新 PRD" / "吸收 PRD 变化" | "incorporate PRD changes" / "ingest PRD diff" |
+
+**DO NOT trigger refresh**:
+
+| 场景 | 走向 |
+|---|---|
+| 「写新 PRD」/「整理需求」/「梳理功能边界」 | 白板模式(v0.1) |
+| PRD 大改 / 几乎重写(7.1 step 0 PM 自报 (c)) | 重跑白板(refresh 不适合大手术) |
+| 单字段修订(只改 owner / 改 AC-7) | 直接 edit yaml 或用 `prd` CLI |
+| 现有 yaml 不存在 | fallback 白板 + 明确告知 |
+
+#### 1.2 (白板模式)识别功能主类型
+
+从用户输入中提取特征,判定功能类型并决定加载哪份 checklist:
+
+| 特征关键词 / 场景 | 功能类型 | checklist 文件 |
+|---|---|---|
+| 批量 / 批处理 / 一次性 / 成批 / 文件上传 / 数据迁移 / CSV / Excel | 批量导入 | `checklists/batch-import.md` |
+| (规划中) 审批 / 流转 / 多级确认 | 审批流 | `checklists/approval-flow.md` |
+| (规划中) 角色 / 权限 / 访问控制 | 权限 | `checklists/permission.md` |
+| (规划中) 站内信 / 邮件 / 推送 / 触达 | 通知 | `checklists/notification.md` |
+
+若识别不出或跨多类型 → 仅依赖模板自身的 [必填] 字段驱动追问,并在 open_questions 加一条"功能类型不明,可能需要定制 checklist"。
+
+### 第 2 步:强制加载资源
+
+**必须读完以下三份文件再开始追问:**
+
+1. `templates/prd.yaml` — 骨架结构、字段定义、标记约定
+2. `checklists/<type>.md` — 该类型功能的边界追问清单
+3. `examples/import-history-prds.prd.yaml` — 金标准范例(仅参考结构,**不照抄具体值**)
+
+**资源定位协议(跨平台路径自适应,按顺序尝试):**
+
+1. **相对路径优先** — `templates/prd.yaml` / `checklists/<type>.md` / `examples/import-history-prds.prd.yaml`
+   (Claude Code skill 默认行为,skill 目录是工作目录)
+2. **项目根 `.prd-skill/` 兜底** — `.prd-skill/templates/prd.yaml` 等
+   (Cursor / Codex / Antigravity 等把 SKILL.md 内容塞进 system prompt 时,子目录通常拷到项目根)
+3. **knowledge / uploads 索引** — ChatGPT Custom GPT 把子目录上传为 knowledge,按文件名查找
+4. **以上全失败** — **不要凭空编造**。明确告知用户"未找到 templates/prd.yaml,请确认子目录已部署到 `<候选路径列表>` 之一",停止流程
+
+**不要凭空生成答案。** 找不到资源就告诉用户,不要假装读过。
+
+### 第 2.5 步:长材料预处理(条件触发)
+
+**触发条件:** 用户一次性投入 ≥ 100 行的聊天记录、会议纪要、旧 PRD 长文,或粘贴了多个文档片段。
+
+**必须先做摘要再追问**(不要直接进入 P0 追问):
+
+1. **摘要 5-10 条关键事实**(出处必须可追溯到原文段落,不要总结成抽象观点)
+   - 已表达的需求点
+   - 已表达的边界 / 约束
+   - 已表达的反对意见 / out_of_scope
+   - 隐含的假设 / 未定决策
+2. **列 3-5 个关键悬而未决的点**(给追问做导航,标"你提到 X,但没说 Y,后续会细问")
+3. **请用户校验摘要**:"以上理解是否准确?有没有漏掉关键点?"
+4. **校验通过后**再进入第 3 步追问;校验有出入则就近修正,不要带着错误前提追问
+
+**目的:** 长材料 token 消耗大,不预处理直接追问会出现"AI 漏看关键约束"或"用户重复回答已在材料里的事"。摘要环节让 AI 和用户对齐"已知事实",追问只补"未知边界"。
+
+**不触发条件:** 用户只给一两句话需求 / 短材料 / 直接就是 P0 答案 → 跳过本步,直接进第 3 步。
+
+### 第 3 步:分轮次追问
+
+遵循 checklist 的执行协议:
+
+- 每轮 3-5 个问题,不要一次性抛一大堆
+- 按 P0 → P1 → P2 顺序,P0 未答完不进 P1
+- 有选项的题给选项(`A / B / C / D / 其他`),不要开放题
+- 每轮结束做"已确认的关键决策"摘要,让用户确认或修正
+- 用户说"够了"或"直接生成"即停止,未答问题进 `open_questions`
+
+**追问数量与优先级**(优先级冲突时按以下顺序让步):
+
+1. **P0 必须问完**(checklist 中所有 P0,通常 5-10 题,跨 1-2 轮) — 不可裁剪,P0 未答完不进 P1
+2. **P1 按预算挑选**(剩余轮次内挑 6-10 题最相关的) — 用户表现配合就多问,显疲态就跳过
+3. **P2 仅当用户积极时问**(2-3 题点缀)— 用户说"够了"立即停止,P2 未答的全进 `open_questions` 标 `non_blocking`
+
+**总轮数 3-5 轮**,**总题数 15-25 题**(批量导入这类中等复杂度功能的典型规模)。简单功能可少,复杂功能可多,但 **P0 完整性 > 问到 P1/P2 数量**。
+
+不要为了凑题数把 P0 拆得过细,也不要为了少问跳过 P0。
+
+### 第 4 步:填充 prd.yaml
+
+以 template 为骨架,按以下规则填写:
+
+- 顶层 key 使用**英文**(和 template 一致,不改名)
+- value 用**中文**(ID 值保留英文前缀,如 `"EN-1"`)
+- **保留**:每个模块头部的 `# === section | 用途 ===` 分隔块
+- **保留**:每个字段右侧的 `-- 中文名` 标签(例如 `id: "EN-1"  # -- 实体`)
+- **可删**:完成填写后的 `[必填] / [选填] / [PM 填] / [CLI 管] / [机器读]` 任务标记注释(这些是给写作者看的脚手架,定稿后无信息量)
+- 长文本用 YAML block style `|`(如 `background`、大段 `rule`)
+- ID 前缀严格遵守:EN / S / R / SC / E / UI / AC / Q / DC / API / PC / SEC
+
+**具体决策值必须来自用户**。用户没说的,放进 `open_questions`,不要代为决策。
+
+### 第 5 步:确定并写入路径
+
+**feature slug 规则:**
+- 小写字母 + 数字 + 连字符
+- 匹配正则 `^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$`
+- 不允许 `_`、空格、中文、大写
+- 若用户给的功能名是中文或含特殊字符,**主动问** slug 该叫什么
+
+**输出路径:**
+```
+.prd/features/<feature-slug>/working/prd.yaml
+```
+
+### 第 6 步:收尾回报
+
+生成完毕后告诉用户:
+
+1. 文件路径
+2. 模块规模(各段填了多少条)
+3. blocking 级 open_questions 的数量和清单
+4. 建议下一步:回答 blocking → `prd validate` → `prd freeze`
+
+### 第 7 步:refresh 工作流
+
+#### 7.0 问 PM 变化规模(强制,不可跳)
+
+> "本次 PRD 变化主要属于哪类?(a) 单字段微调(1-2 处) (b) 几处协同变化(几个模块新增/删除/修改) (c) 几乎重写一半以上"
+
+- (a) → 建议「直接 edit yaml 或 `prd` CLI 单点改」,不必走 refresh 全流程
+- (b) → 进入 refresh,后续步骤照走
+- (c) → 建议「重跑白板模式从头生成」,refresh 不适合大手术
+- 用户选 (a) 或 (c) → 明确转出口,不强制走完 refresh
+
+#### 7.1 前置检查
+
+- `.prd/features/<slug>/working/prd.yaml` 存在 → 继续
+  - 不存在 → fallback 白板模式,明确告知用户
+- 用户给了新 PRD?
+  - 没给 → 询问路径或让粘贴文本
+  - 给了 → 继续
+- 新 PRD 是 markdown(.md)?
+  - 是 → `--prd-anchor` 可用
+  - 不是(docx / pdf / 粘贴文本) → 跳过 anchor,AI 读全文
+
+#### 7.2 调 CLI 拿索引视图
+
+```bash
+prd refresh --feature <slug> \
+  [--new-prd <path>] \
+  [--prd-anchor <heading>] \
+  [--prd-anchor-exact]
+```
+
+CLI 失败(yaml 找不到 / anchor 不命中 / 多匹配 / fs 错)→ 停止,转告 stderr。
+
+#### 7.3 长材料预处理(复用第 2.5 步规则)
+
+新 PRD ≥ 100 行 → 先摘 5-10 条关键事实 + 3-5 个未决点 → 请用户校验
+短 PRD → 跳过
+
+#### 7.4 AI 语义 diff
+
+AI 拿「索引视图 + refers_to 反向图 + entry titles dump + 新 PRD」产字段级变化清单,**分 4 组**呈现:
+
+- `[+]` 新增
+- `[-]` 删除
+- `[~]` 修改
+- `[⚠]` 边界变更
+
+每条变化标:
+- yaml 字段 ID + 行号
+- 变化前 → 变化后
+- 推测来源(PRD 行号或段落标题)
+- 若涉及被引用字段:附 `refers_to` 反向图警示
+
+**7.4 末尾必须给变化规模摘要**(关联 design 6.5 O-2 关闭决策):AI 一行总结「本次变化涉及 N 个模块、共 X 处(其中 +A 新增 / -B 删除 / ~C 修改 / ⚠D 边界)」给 PM 自决是否换白板;**不用数字阈值强制阻断**。
+
+#### 7.4.5 AI 自报覆盖盲区(防漏看关键步骤)
+
+AI 在 7.4 完成后,**必须输出**:
+
+1. 「本次诊断覆盖的 yaml 模块清单」—— 显式列出 AI 在 diff 时检查过哪几个模块
+2. 「未动过的模块清单」—— 显式列出完全没改的模块,提醒 PM 复核
+3. 「**entry titles dump cross-check**」—— 用索引视图末尾的 entry titles 全清单,逐个在新 PRD 中 grep:
+   - 全部命中 → OK 不动
+   - 完全没出现 → 候选删除,加入 `[-]` 组提示 PM
+   - 部分命中(标题变更) → `[~]` 修改组
+
+#### 7.5 PM 逐条决策
+
+每条:**接受 / 拒绝 / 修改文本**(三选一)
+
+- 同类批量(如砍 12 处自动考核):可一次「批量接受 / 拒绝」
+- **边界变更 / refers_to 断链:P0 强制逐条确认**,不可批量默认
+- PM 填关键决策的 rationale:**边界变更 / `[⚠]` 类必填**;其他类可选填
+
+#### 7.6 写盘 + 收尾(三步,严格顺序)
+
+**Step 1**:内存中改完整个 yaml(parse → modify → serialize),不落盘
+**Step 2**:内存中拼好 CHANGELOG 新段(append 到既有 [Unreleased] 末尾的字符串),不落盘
+**Step 3**:落盘(**严格顺序:先 CHANGELOG → 后 yaml**)
+
+1. 先写 `working/CHANGELOG.md`(metadata,失败容忍度高)
+   - 若失败:yaml 未动,可直接重试,无副作用
+2. 再写 `working/prd.yaml`(真相源,失败影响大)
+   - 若失败:CHANGELOG 已 append 但 yaml 未生效;告知用户「yaml 写入失败,可手工 revert CHANGELOG.md 末段或忽略」
+
+**Step 4**:跑 `prd validate` 自检
+**Step 5**:收尾告知:
+- N 处变化已应用 / X 处拒绝 / Y 处新 open_questions
+- 文件路径(yaml + CHANGELOG.md)
+- 自检结果(若新 blocking 必须明示)
+- 下一步建议:解决 blocking → `prd freeze v1.1`
+
+---
+
+## 硬规则(8 条,违反即为 Skill 执行错误)
+
+### 规则 1:不照抄范例的具体占位值
+
+范例 `examples/import-history-prds.prd.yaml` 里的所有:
+- 邮箱(`pm-alice@example.com`)
+- 日期(`2026-04-29`、`2026-04-22`)
+- 人名(`pm-alice`、`架构负责人`)
+- 具体 slug(`import-history-prds`)
+- 具体约束值(`5MB`、`50 个文件`、`正则 ^[a-z0-9]...`)
+
+**都是演示占位值**。生成新 PRD 时:
+- 用户提供真实值 → 用真实值
+- 用户没提供 → 留 `""`,在 `open_questions` 加一条请用户补充
+- **绝不照抄范例**
+
+### 规则 2:[CLI 管] 字段留空或填固定初值
+
+template 标 `[CLI 管]` 的字段由 CLI 维护,AI 不得手填具体运行值。
+
+| 字段 | 生成时填什么 |
+|---|---|
+| `schema_version` | `"v0.2"` |
+| `meta.team` | (PM 提供的 team slug,kebab-case,如 `prd-improve`) |
+| `meta.lifecycle.version` | `"working"` |
+| `meta.lifecycle.status` | `"draft"` |
+| `meta.lifecycle.updated_at` | `""` (留空,CLI 首次写入时填充) |
+
+其他 `[CLI 管]` 字段一律 `""` 或 `[]`。
+
+### 规则 3:`ui_interaction` 可以整体为空
+
+纯后台功能(API / 定时任务 / 数据同步 / 异步 worker)没有 UI,直接写:
+
+```yaml
+ui_interaction: []
+```
+
+**不要硬编一个"任务监控面板"凑数**。UI 是否存在由功能本身决定。
+
+### 规则 4:写业务要求,不写技术实现选型
+
+`data_and_api` 和 `edge_cases` 写的是**业务级约束**(任何合理实现都必须遵守),不是**技术选型**(开发可换的实现方案)。
+
+**不得**出现(具体协议 / 算法 / 选型):
+- `idempotency_key` 的具体哈希算法、字段拼接顺序
+- 指数退避、重试间隔的具体公式(如"重试间隔 = 2^n × 100ms")
+- 长轮询 / WebSocket / SSE / gRPC 等通信协议选型
+- JWT / OAuth / 签名机制 / token 刷新策略 等具体认证协议选型
+- 数据库 DDL、索引、分表策略
+- 前端框架、组件库、状态管理库选型
+
+**可以**出现(业务要求 / 业务上限 / 业务可见行为):
+- "任务创建接口需支持幂等(同 initiator + 同文件集合 + 60 秒窗口返回同 task_id)" — 业务要求
+- "worker 失败后重试,最多 2 次" — 业务上限,而非"如何重试"
+- "失败文件下载链接需鉴权,链接有效期 ≤ 10 分钟" — 业务要求 + 上限,而非"用签名 URL"
+- "列表首屏 ≤ 2s" — 业务可观察的性能指标
+
+**判定标准**(当你拿不准时问自己):
+- 这条约束换一种合理实现方式还成立吗?成立 → 业务约束,可写
+- 这条约束写的是"做什么"还是"怎么做"?前者可写,后者删
+- 业务方关心这个数字 / 行为吗?关心 → 写;只是开发实现细节 → 删
+
+**正确改写示例:**
+- ❌ "失败清单 CSV 用 S3 签名 URL 下载,有效期 10 分钟"
+- ✅ "失败清单 CSV 下载链接需鉴权,有效期 ≤ 10 分钟"
+
+### 规则 5:state_permissions 写差异化,不模板化复述
+
+**坏例子**(每个状态都复述一遍"查看任务详情"):
+```yaml
+state_permissions:
+  - entity_id: "EN-1"
+    state: "pending"
+    allowed_actions:
+      - action: "查看任务详情"
+        roles: ["产品经理"]
+  - entity_id: "EN-1"
+    state: "parsing"
+    allowed_actions:
+      - action: "查看任务详情"
+        roles: ["产品经理"]
+  # ... 4 次重复 ...
+```
+
+**好例子**(只写该状态差异化的权限):
+```yaml
+state_permissions:
+  - entity_id: "EN-1"
+    state: "pending"
+    allowed_actions:
+      - action: "取消任务"
+        roles: ["产品经理", "工作空间管理员"]
+        notes: "pending 取消无副作用"
+  - entity_id: "EN-1"
+    state: "parsing"
+    allowed_actions:
+      - action: "取消任务"
+        roles: ["产品经理", "工作空间管理员"]
+        notes: "已完成的文件保留,未处理的丢弃"
+  - entity_id: "EN-1"
+    state: "succeeded"
+    allowed_actions:
+      - action: "下载失败清单"
+        roles: ["产品经理", "工作空间管理员"]
+```
+
+**跨状态通用的权限**(如"查看详情"、"PM 只能看自己的任务")→ 放在 `data_and_api.security_constraints` 或 `business_rules` 统一声明一次。
+
+### 规则 6:entities.fields 写业务字段,不写 DB schema
+
+**坏例子**(通用技术字段,写了等于没写):
+```yaml
+fields:
+  - name: "id"
+    type: "uuid"
+  - name: "created_at"
+    type: "datetime"
+  - name: "updated_at"
+    type: "datetime"
+  - name: "deleted_at"
+    type: "datetime"
+```
+
+**好例子**(业务关键字段 + 特殊约束字段):
+```yaml
+fields:
+  - name: "initiator"
+    type: "reference<用户>"
+    required: true
+    notes: "发起者,影响 state_permissions 判定"
+  - name: "file_count"
+    type: "int"
+    required: true
+    notes: "本次提交文件总数,创建后不变"
+  - name: "error_code"
+    type: "string"
+    required: false
+    notes: "枚举:FILE_TOO_LARGE / ENCODING_ERROR / SLUG_CONFLICT_IN_BATCH / ..."
+```
+
+**原则:**
+- 列业务必需字段(状态、身份、计数、业务枚举)
+- 列有特殊约束的字段(格式、上限、唯一性)
+- 不列 `id / created_at / updated_at / deleted_at / version` 等通用字段(开发按 convention 补)
+- 如果字段就是 `id` 但有特殊规则(如 slug 正则),则写并标注规则
+
+### 规则 7:MVP 降级协议
+
+用户明确说"只做最简版"、"先跑通 MVP"、"快速出第一版"、"细节先不要" 等表态时,**触发降级**:
+
+**降级目标:** 保证 4 个核心模块完整,其他模块允许"骨架 + open_questions",不阻塞 freeze。
+
+**核心模块(必须完整)**:
+- `meta`(版本信息)
+- `in_scope`(本期范围)
+- `out_of_scope`(明确不做 — 降级时尤其重要,把砍掉的点显式记下来)
+- `acceptance_criteria`(验收标准 — 至少覆盖 in_scope 的每条)
+
+**其他模块降级处理**:
+- P0 已答的事实 → 正常填入对应模块
+- P1 / P2 未答的题 → 全部转 `open_questions`,`severity: non_blocking`,`deferred_to: "v1.1"`
+- 整个 `scenarios` / `edge_cases` 写 1-2 条"Happy Path"占位即可,其余 → `open_questions`
+- `state_permissions` / `business_rules` 只写 P0 答出来的,其他 → `open_questions`
+
+**收尾时必须告知用户:**
+
+> 已按 MVP 模式生成。核心 4 模块完整,其他模块仅占位 + open_questions(共 N 条 non_blocking)。
+> 进入 v1.1 前需回答这些问题以补全 PRD;但本期可直接 `prd validate` 通过(blocking 数为 0)。
+
+**禁止**降级时凭空补 P1/P2 答案,这是 skill 最容易翻车的点 —— 用户说"简化"是要少做,不是要 AI 替他做决策。
+
+### 规则 8:refresh 模式联动改动需逐条 PM 确认
+
+(仅 refresh 模式生效。"AI 不凭空填字段值" 已在硬规则 #1 涵盖,本规则聚焦联动)
+
+refresh 模式下,**因 PRD 删除 / 修改 + refers_to 引用关系**而产生的"联动改动"必须经 PM 逐条确认,不可自动应用。
+
+**不得**:
+- 新 PRD 删了某段而 yaml 里有对应实体,AI 自动从 yaml 删
+  (必须 P0 问 PM:是真砍还是 PRD 漏写?)
+- 因 `refers_to` 联动,AI 自动改 SC-4 / E-2(改 R-3 时被引用方必须 PM 单独确认)
+- AI 推测出的变化跟 PRD 原文不一致(必须停下问 PM,不可自动应用)
+
+**只可**:
+- PRD 文本明确说的字段,应用并标 source(PRD 行号 / heading)
+- PM 在对话中明确指示的变化(标 rationale 由 PM 提供)
+- `refers_to` 联动仅作"提示"出现在 diff 清单中,不直接应用
+
+**与 7.5「批量接受」的边界**:批量接受只限**同一类同一字段**的变化(如"批量接受 12 处自动考核相关字段的删除"),**不跨字段联动**;refers_to 反向图中的"被引用字段"必须单独逐条决策。
+
+---
+
+## 未回答问题的去向
+
+用户说"够了"或明显不愿继续答时:
+
+| 优先级 | severity | deferred_to |
+|---|---|---|
+| **P0 未答** | `blocking` | `""` |
+| **P1 未答** | `non_blocking` | `"v1.1"` 或 `""` |
+| **P2 未答** | `non_blocking`(或可丢弃) | `"v2"` 或 `""` |
+
+**owner 字段:**
+- 用户明确指定 → 填真实值
+- 用户没说 → 填 `"待指派"`,不要填 `pm-alice` 之类占位
+
+---
+
+## 典型对话模板
+
+> ⚠️ 以下数字(3-4 轮、5 个问题、5 scope / 2 entities / 10 AC)**仅为本范例的实际规模**,
+> **不是目标也不是上限**。实际轮数和模块规模按功能复杂度调整 ——
+> 简单功能 1-2 轮就够,复杂功能 5-6 轮也合理;entities 可能只有 1 个或多达 5 个;
+> AC 取决于场景与边界数量。**P0 完整性 > 凑出特定规模**(M5 优先级)。
+
+### 用户输入
+
+> 帮我把"批量导入历史 PRD 文件"整理成 PRD
+
+> ⚠️ 当用户一次性投入 ≥ 100 行长材料(聊天记录 / 会议纪要 / 旧 PRD)时,
+> 在"第 1 轮"前**必须先插入一轮摘要校验轮**(执行第 2.5 步):
+> 列 5-10 条已知事实(出处可追溯到原文段落)+ 3-5 个悬而未决的关键点,
+> 请用户确认或修正后再进 P0 追问。
+> 短材料 / 一句话需求(下面的范例)直接从"第 1 轮 · 识别 + 基础确认"开始。
+
+### AI 响应(短材料场景,4 轮)
+
+**第 1 轮 · 识别 + 基础确认:**
+
+> 这是一个批量导入类功能,我会按 PRD Improve 规范帮你整理。
+> 大约 3-5 轮追问(每轮 3-5 个问题),先问 P0 边界,再逐步细化。
+> 你任何时候说"够了"都可以,未回答的关键问题会记在 open_questions 里。
+>
+> 先确认基础项:
+> 1. feature slug 用什么?(英文小写连字符)
+> 2. workspace / project 叫什么?
+> 3. 你是这个功能的 PM 负责人吗?用什么邮箱?
+
+**第 2 轮 · P0 核心边界:**
+
+> 接下来问 5 个最关键的:
+> 1. 数据从哪里来?(本地上传 / URL / API / 粘贴 / 其他)
+> 2. 支持哪些文件格式?(CSV / Excel / MD / JSON / ...)
+> 3. 遇到重复数据如何处理?(覆盖 / 跳过 / 报错 / 让用户选)
+> 4. 是否允许部分成功?(允许 / 不允许全量回滚 / 让用户选)
+> 5. 同一批次里两份文件指向同一实体,怎么办?
+
+**第 3 轮 · P0 剩余 + P1 关键:**
+
+> 再问几个:
+> 1. 任务进行中,用户能再发起第二个吗?
+> 2. 浏览器关闭后回来看到什么?
+> 3. 追加这件事本期要做吗?追文件还是追数据?
+> 4. 失败的文件数据保留多久?
+> 5. 哪些角色能发起导入?
+
+**收尾:**
+
+> 好,已经够生成完整 PRD。梳理关键决策:
+> - [摘要已确认的决策项]
+> - [列出 blocking 待确认问题]
+>
+> 确认无误就生成 `.prd/features/<slug>/working/prd.yaml`。
+
+**生成后:**
+
+> 生成完毕:
+> - 路径:`.prd/features/<slug>/working/prd.yaml`
+> - 模块规模:5 scope / 2 entities / 5 rules / 5 scenarios / 7 edge cases / 10 AC
+> - 待确认问题:6 条(2 blocking / 4 non_blocking)
+>
+> 建议下一步:
+> 1. 回答 2 条 blocking(阻塞冻结)
+> 2. `prd validate` 校验完整性
+> 3. 完整通过再 `prd freeze --local --version v1.0`
+
+### refresh 模式范例(简化版,3 轮)
+
+**用户输入**(refresh 触发):
+> PRD 升级到 v2.6 了,帮我把 yaml sync 一下
+
+**第 1 轮 · 前置 + step 0 + 资源**:
+
+> 检测到 refresh 模式。先确认变化规模:
+> (a) 单字段微调 / (b) 几处协同变化 / (c) 几乎重写一半以上 →
+>
+> 用户:(b)
+>
+> OK,进入 refresh 流程。请确认:
+> 1. feature slug 是?(若不确定,我列举 `.prd/features/` 下的)
+> 2. 新 PRD 文件路径?(或贴文本)
+> 3. PRD 文件大,需要章节锚点切片吗?(可选,如 "FR-RECRUIT-004")
+
+**第 2 轮 · 字段级 diff + 自报覆盖**:
+
+> 调 `prd refresh --feature candidate-pipeline --new-prd prd-2.6.md` 后,共发现 17 处字段变化:
+>
+> [-] 删除(自动考核相关 12 处):S-3 / EN-2 / R-3-5 / SC-4 / AC-4-6 / UI-5 / DC-5-6 / E-2-4
+>     源:PRD v2.5 → v2.6 第 5.2 节砍除
+>     ➤ 批量接受?[y/n/逐条]
+>
+> [~] 修改 R-7 资质校验链:加 configurable_order 字段
+>     源:PRD 第 5.3 节
+>     ⚠ refers_to:SC-7 / AC-15 引用 R-7,需联动看
+>     ➤ 接受 / 拒绝 / 修改?
+>
+> [自报] 本次诊断覆盖了 8 模块(in_scope / entities / business_rules / scenarios / acceptance_criteria / state_permissions / data_and_api / open_questions),未动过 2 模块(edge_cases / ui_interaction)— PM 请复核这两个模块是否真的没变。
+> [cross-check] entry titles 全清单逐个在新 PRD 中 grep:全部命中,无候选删除。
+
+**第 3 轮 · 收尾**:
+
+> 已应用 14 处 / 拒绝 2 处 / 1 处转 open_questions:
+> - 路径:`.prd/features/candidate-pipeline/working/prd.yaml`(已修改)
+> - 路径:`.prd/features/candidate-pipeline/working/CHANGELOG.md`(已 append 一段 [Unreleased])
+> - `prd validate` 自检:PASS(15/15 模块 + 0 引用错 + 0 blocking)
+>
+> 下一步:`prd freeze v1.1` 把这版固化。
+
+---
+
+## 跨平台兼容
+
+本 Skill 遵循 Claude Skill 格式。在其他 AI 工具中使用:
+
+| 平台 | 用法 |
+|---|---|
+| **Claude Code / Claude.ai** | 复制 `packages/skill/prd-improve-forge/` 到 `~/.claude/skills/` |
+| **Cursor** | SKILL.md 内容粘贴到项目 `.cursorrules`;`templates/` / `checklists/` / `examples/` 放项目根的 `.prd-skill/` |
+| **ChatGPT / Custom GPT** | SKILL.md 作为 system prompt;三个子目录上传为 knowledge |
+| **Codex / Antigravity** | SKILL.md 内容放 system prompt / rules;子目录放项目根 |
+
+**核心工作流不变**:识别模式 + 类型 → 加载资源 → (长材料先摘要) → 分轮追问 / refresh diff → 严格遵守 8 条硬规则 → 输出到 `.prd/features/<slug>/working/prd.yaml`(白板)或就地更新 + CHANGELOG append(refresh)。
+
+---
+
+## 版本与维护
+
+**当前版本:** SKILL.md v0.2 · 对应 schema_version v0.2(refresh mode added 2026-05-12)
+
+**支持的 checklist 类型:**
+- [x] `batch-import` (批量导入)
+- [ ] `approval-flow` (审批流,规划中)
+- [ ] `permission` (权限,规划中)
+- [ ] `notification` (通知,规划中)
+
+**何时需要更新本 Skill:**
+
+1. **新功能类型出现** → 添加新 checklist 文件,本 SKILL.md 第 1 步的识别表加一行
+2. **模板 schema 升级** → 同步升级 schema_version,检查所有 checklist 引用的字段是否还存在
+3. **反复踩同一个坑** → 在"硬规则"段新增一条并给坏例子 / 好例子
+4. **触发不准** → 修改 frontmatter 的 description,连续观察 2 周