---
name: forge-prd
description: '产品诊断与 PRD 迭代管理器。用户描述遇到的问题或需求，skill 诊断根因（产品设计缺陷/实现偏离/PRD遗漏）、审查模块健康度、设计方案、挑战假设、必要时反驳需求，最终更新 PRD 和 CHANGELOG。支持从零创建 PRD、迭代已有 PRD，并记录前端/全栈需求的视觉决策需求（Image 2/Figma/真实截图）。触发方式：用户说"更新PRD"、"调整需求"、"迭代PRD"、"forge-prd"、描述产品问题、需要修改项目产品需求时使用。'
---

> **文档落地路径**：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见
> `~/claudecode_workspace/工具/forge-cookbook/skills/forge-doc-policy/doc-paths.md`。

# /forge-prd：产品诊断与 PRD 迭代管理器

## 流程总览

```
用户报告症状/需求
  → 第0步：定位项目、PRD、CHANGELOG
  → 第1步：理解现状（读 PRD + CHANGELOG + 源码）
  → 第2步：诊断与审查（自适应三层深度）
  → 第3步：方案确认（多轮交互 → 用户最终确认变更清单）
  → 第4步：写入文档（确认后才写 CHANGELOG + PRD 更新 + 迭代交付说明）
```

全程中文。每个步骤结束后暂停等待用户反馈。

### 交互流程图

```
用户描述问题/需求
       │
       ▼
┌─ 第0步：定位 ──────────────────────────┐
│  Glob 搜索 PRD / CHANGELOG              │
│  ├─ 找到 PRD → 迭代模式                 │
│  ├─ 没找到 → [询问用户] 是否创建模式     │
│  └─ 没找到 CHANGELOG → 标记第4步新建     │
└──────────────────────────────────────────┘
       │
       ▼
┌─ 第1步：理解现状 ─────────────────────────┐
│  读 PRD + CHANGELOG + Agent(Explore)源码   │
│  热点分析（模块修改频次）                   │
│  → [询问用户] 总结现状，确认理解是否正确    │
│  → [询问用户] 本次迭代需求是什么？          │
└─────────────────────────────────────────────┘
       │
       ▼
┌─ 第2步：诊断与审查 ──────────────────────────┐
│  自动判定层级：轻量 / 标准 / 深度             │
│  ┌─ 所有层级 ─────────────────────────┐      │
│  │  ① 问题归因（设计缺陷/偏离/遗漏）  │      │
│  │  ② 10星挑战（当前几星→10星差距）    │      │
│  └─────────────────────────────────────┘      │
│  ┌─ 标准+深度 ─────────────────────────┐     │
│  │  ③ 模块健康度检查                   │      │
│  └─────────────────────────────────────┘      │
│  ┌─ 仅深度 ───────────────────────────┐      │
│  │  ④ 假设审查  ⑤ 反驳机制            │      │
│  └─────────────────────────────────────┘      │
│  → [询问用户] 展示诊断结果，确认方向         │
└───────────────────────────────────────────────┘
       │
       ▼
┌─ 第3步：方案确认 ─────────────────────────────┐
│  逐项讨论变更点（当前→目标→推荐→可选）        │
│  → [多轮询问用户] 每个变更点确认               │
│  → [询问用户] 汇总变更清单，最终确认           │
│  ⚠️ 门禁：确认前不写任何文件                   │
└────────────────────────────────────────────────┘
       │ 用户确认 ✓
       ▼
┌─ 第4步：写入文档 ─────────────────────────────┐
│  A. 更新/新建 CHANGELOG                       │
│  B. 更新 PRD 正文（版本号+迭代摘要+功能章节）  │
│  C. 产出迭代交付说明（面向下游 Agent）          │
│  → 输出最终总结                                │
└────────────────────────────────────────────────┘
```

---

## 可视化规范

**核心原则**：在向用户展示信息时，动态判断是否使用 widget 可视化。**不是所有内容都需要画图**——只在可视化明显优于纯文本时才使用。

如判断需要可视化，先读取 `../_shared/visual-decision-layer.md`：
- **Mermaid / show-widget** 用于流程、因果、矩阵、健康度、10 星挑战等结构化判断。
- **Image 2** 用于前端观感、页面气质、复杂状态、用户需要“看见效果”才能确认的决策。
- PRD 阶段不把 Image 2 当成设计定稿；只记录视觉决策需求、已有图链接和下游 `forge-design` 必须补齐的视觉稿。

**判断标准**（满足任一即用 widget）：
- 有**对比关系**：方案 A vs B、当前 vs 目标、版本间差异
- 有**多维度数据**：≥3 个模块的评分/状态/频次需要并排展示
- 有**流程/因果链**：多步骤流程、归因路径、决策树
- 有**统计分布**：频次、占比、趋势等数值型数据
- 信息量大且**结构化程度高**：变更清单 ≥5 项、多模块健康度评估

**不需要 widget 的场景**：
- 简单的 1-2 句确认性问题
- 单个变更点的讨论（纯文字更直接）
- 用户只需要 yes/no 的决策
- 信息本身就是线性叙述，没有对比或结构

**使用前**：首次生成 widget 前，调用 `mcp__codepilot-widget__codepilot_load_widget_guidelines` 加载设计规范。

**推荐的 widget 类型参考**：

| 信息类型 | 推荐 widget | 典型场景 |
|----------|-------------|----------|
| 多指标概览 | 指标卡片仪表盘 | 产品状态总结、迭代完成总结 |
| 频次/分布数据 | Chart.js 柱状图 | CHANGELOG 热点分析、变更统计 |
| 因果/流程 | SVG 流程图 | 问题归因路径、决策流程 |
| 多维评估 | SVG 矩阵/评分卡 | 模块健康度、方案评分 |
| A vs B | SVG 并排对比 | 当前 vs 目标、方案对比、10星挑战 |
| 结构化清单 | 交互式 HTML | 变更清单（≥5项时） |

**设计要求**（当决定使用 widget 时）：
- 遵循 widget guidelines 的配色和布局规范（Indigo 主色，Slate 结构色）
- 每个 widget ≤ 3000 字符，解释文字放在代码块外
- SVG 使用 `width="100%" viewBox="0 0 680 H"`
- Chart.js 图表必须 responsive，禁用 legend
- 复杂信息拆成多个 widget，交替文字和可视化

---

## AskUserQuestion 格式规范

每次提问遵循以下结构：

1. **重新聚焦**：说明当前项目名称和正在讨论的变更。（1-2句）
2. **通俗解释**：用简单语言说清楚要做什么、为什么。不用函数名、不用内部术语。
3. **最佳方案**：作为 CEO 和专业 AI 产品经理寻找和思考最佳方案。
4. **给出推荐**：`推荐：[方案X]，因为[一句话原因]`。标注完整度 X/10。
5. **列出选项**：`A) ... B) ... C) ...`。
6. **可视化辅助**（按需）：如果选项涉及 ≥3 个方案对比或复杂的流程差异，用 `show-widget` 渲染对比图辅助决策。简单的 A/B 选择不需要画图。

假设用户已经20分钟没看窗口。如果你需要读源码才能理解自己的解释，说明解释太复杂了。

---

## 第0步：定位项目、PRD 与 CHANGELOG

1. 根据用户提供的目录线索，用 Glob 搜索 PRD 文件：
   ```
   搜索模式（按优先级）：
   - {项目目录}/docs/PRD.md
   - {项目目录}/docs/prd.md
   - {项目目录}/docs/*PRD*
   - {项目目录}/docs/*需求*
   - {项目目录}/PRD.md
   - {项目目录}/**/PRD*.md
   ```

2. 搜索 CHANGELOG 文件（不写死文件名，模式匹配）：
   ```
   搜索模式：
   - {项目目录}/docs/*changelog*（不区分大小写）
   - {项目目录}/docs/*CHANGELOG*
   - {项目目录}/docs/*变更*
   - {项目目录}/**/CHANGELOG*
   - {项目目录}/**/changelog*
   ```

3. 分支判断：
   - 找到 PRD → 进入「迭代模式」（第1步）
   - 找不到 PRD，和用户确认是否进入「创建模式」，用户确认后生成PRD（第1步-替代）
   - 找不到 CHANGELOG → 标记需要在第4步新建（基于项目文档 + git history 回溯生成）

---

## 第1步：理解现状（迭代模式）

1. 读取完整 PRD 文档
2. 读取 CHANGELOG（如果存在），了解历史变更
3. **CHANGELOG 热点分析**：
   - 统计各模块被修改的频次
   - 识别「反复修改但未根治」的模块（同一模块在多个版本中出现）
   - 如果发现热点模块与用户本次需求相关，主动提示
4. 用 Agent 工具深度分析项目源码：
   - 使用 Explore 子代理扫描项目结构、关键文件、技术栈
   - 重点关注：当前实现与 PRD 描述的差异、用户描述的问题
5. 向用户总结当前产品状态（3-5句），确认理解是否正确
   - 如果项目模块较多（≥4个）或存在热点模块数据，考虑用 widget 渲染指标卡片和热点柱状图
   - 简单项目直接文字总结即可
6. 询问用户本次迭代的需求或问题

---

## 第1步（替代）：从零创建 PRD

当项目没有 PRD 文件时执行此流程。

1. **全面阅读项目代码**：
   - 用 Agent(Explore) 系统性扫描项目目录结构
   - 读取 README、package.json/requirements.txt 等配置文件
   - 读取核心源码文件，理解功能模块
   - 读取数据库 schema（如有）
   - 查看 git log 了解项目演进历史

2. **与用户多轮确认**（每轮一个主题，通过 AskUserQuestion）：
   - 第1轮：产品定位 — "这个项目解决什么问题？给谁用？核心价值是什么？"
   - 第2轮：功能边界 — 列出从代码中识别到的功能模块，确认是否完整
   - 第3轮：技术约束 — 确认技术限制、第三方依赖、性能要求
   - 第4轮：已知问题 — 确认当前存在的 bug 或体验问题
   - 第5轮：后续规划 — 确认近期计划做的功能

3. **产出 PRD 初稿**：
   - 参考 [references/prd-template.md](references/prd-template.md) 的标准章节结构
   - 写入 `{项目目录}/docs/PRD.md`

4. **新建 CHANGELOG**：
   - 基于项目文档 + git history 回溯生成历史版本记录
   - 记录 v1.0 初始版本
   - 写入 `{项目目录}/docs/` 下

5. 向用户展示 PRD 结构和各章节概要，逐节确认后写入文件

---

## 第2步：诊断与审查（自适应深度）

### 审查深度自动判定

| 层级 | 触发条件 | 做什么 |
|------|----------|--------|
| **轻量审查** | 单个小改动（改阈值、调文案、修参数） | 归因 → 10星挑战 → 确认方案 |
| **标准审查** | 功能调整、多个小改动集中在同一区域 | 归因 + 模块健康度 + 10星挑战 + 方案对比 |
| **深度审查** | 新模块、架构调整、或 CHANGELOG 显示某模块反复修改 | 假设审查 + 10星挑战 + 反驳机制 |

**自动升级规则**：
- 多个小需求集中在同一模块 → 从轻量升级到标准
- CHANGELOG 中某模块在 ≥3 个版本中被修改 → 升级到深度，主动告知用户："这个模块已经在 vX.X、vX.X、vX.X 中反复修改，建议做一次彻底审查"
- 用户主动要求更深度的审查 → 升级

### 诊断流程（所有层级通用）

1. **问题归因**：
   - **产品设计缺陷**：PRD 中对该场景的定义就不完整或不合理
   - **实现偏离 PRD**：PRD 写得对但代码实现偏离了
   - **PRD 遗漏场景**：PRD 根本没考虑到这个场景
   - 明确告知用户属于哪种情况

2. **10星挑战**（所有层级必做）：
   - 当前方案几星？
   - 10星版本是什么样的？
   - 差距是"小"（可以做完）还是"大"（超出当前范围）？
   - 轻量审查：简要挑战即可（1-2句）
   - 标准/深度审查：展开讨论，用并排对比图展示当前 vs 10星方案

3. **模块健康度检查**（标准/深度层级）：
   - 该模块在 CHANGELOG 中的修改历史
   - 该模块当前实现与 PRD 的一致性
   - 是否存在关联模块需要同步调整

### 深度审查额外步骤（借鉴 cn-plan-product）

4. **假设审查**：
   - PRD 中对该模块的隐含假设是什么？
   - 这些假设是否仍然成立？
   - 用户的新需求是否暴露了错误的假设？

5. **反驳机制**：
   - 如果认为用户提的需求放在这里不合适，直接说出来
   - 给出替代方案或建议砍掉某些不需要的功能
   - 从整体产品视角评估，而非只看单个需求点

### 诊断输出

向用户展示：
- 问题归因结果
- 模块健康度评估（如适用）
- 建议的方向：新增功能 / 优化现有功能 / 砍掉不需要的功能 / 调整架构

**可视化判断**：根据诊断复杂度决定是否用 widget：
- 归因路径涉及多个因果环节 → 用 SVG 流程图展示归因链
- 涉及多个模块的健康度评估 → 用 SVG 评分卡矩阵（Emerald=健康，Amber=需关注，Rose=需修复）
- 10 星挑战（标准/深度层级） → 用并排对比图展示当前 vs 10星方案
- 单一明确问题 → 直接文字说明即可

等待用户确认方向后进入第3步。

---

## 第3步：方案确认

通过 AskUserQuestion 逐项讨论每个变更点：

1. **当前行为**：现在是什么样的
2. **目标行为**：期望变成什么样的
3. **推荐方案**：给出推荐并说明理由
4. **可选方案**：列出替代方案（如有），标注完整度
5. **做与不做**：明确确认什么做、什么不做、什么推迟，以及原因

**可视化判断**：
- 单个变更点的讨论 → 文字即可
- 多个可选方案需要对比 → 用 SVG 并排对比图展示各方案优劣
- 变更点涉及复杂的行为差异 → 用「当前 vs 目标」对比图

讨论完成后，汇总变更清单：
- 变更项 ≤3 个 → 文字清单
- 变更项 ≥4 个 → 考虑用交互式 widget 汇总（含类型颜色编码和优先级标注）

通过 AskUserQuestion 请用户最终确认。

**⚠️ 关键门禁：在用户明确确认变更清单之前，不得写入任何文件（CHANGELOG、PRD）。** 第3步的产出仅在对话中展示，不写入磁盘。

---

## 第3.5步：生成 Feature Spec（用户确认门禁）

**前提：第3步变更清单已确认。** 在写入任何文件之前，先生成 Feature Spec 给用户审阅。

### 目的

Feature Spec 是整个开发和 QA 的**行为契约**。它同时服务于：
1. **向用户说明**：整体交互设计和界面结构（全局→细节），让用户判断方向是否正确
2. **向 QA 提供**：可执行的验收检查表（Given/When/Then 场景），让测试有锚点

### 生成流程

1. **读取参考模板**：[references/feature-spec-template.md](references/feature-spec-template.md)
2. **结合第3步的变更清单**，逐节生成 Feature Spec：
   - **用户流程总览**：从全局视角画出用户在该功能中的完整流转路径（入口→步骤→出口），包含异常分支
   - **页面/系统结构**：
     - 前端项目：整体布局 → 各区块职责 → 具体组件（名称、职责、交互行为、CSS 约束）
     - 后端项目：API 拓扑 → 模块职责 → 数据流
     - 全栈项目：两者都写
   - **视觉决策记录**（前端/全栈必填）：
     - 已有 brainstorm / Image 2 / Figma / 真实截图链接
     - 仍需 `forge-design` 生成的视觉稿清单（桌面端、移动端、关键空态/错态）
     - 用户已经确认或明确否定的视觉方向
   - **行为场景**：每个功能点 3 个 Given/When/Then 场景（正常 / 异常 / 边界），使用 SHALL/MUST 标记强制要求
   - **验收检查表**：从行为场景自动提取，分为功能验证、视觉/设计合规（含具体 CSS 值）、流程完整性三类

3. **措辞规范**（吸收 RFC 2119）：
   - **SHALL / 必须** = 强制要求，违反即为 bug
   - **SHOULD / 应该** = 推荐，有合理理由可偏离
   - **MAY / 可以** = 可选

4. **视觉合规项**：如果存在 DESIGN.md，从中提取具体的 CSS 约束（颜色、字号、间距、圆角等）写入验收检查表。不只描述视觉意图，SHALL 包含具体属性值。

### 用户确认（⚠️ 关键门禁）

Feature Spec 生成后，通过 AskUserQuestion 展示给用户：

```
Feature Spec 已生成，请审阅：

一、用户流程：{流程概要，2-3 句话}
二、页面结构：{区块数量} 个区块，{组件数量} 个组件
三、行为场景：{功能点数量} 个功能点，共 {场景数量} 个场景
四、验收检查表：{检查项数量} 项（功能 X 项 + 视觉 Y 项 + 流程 Z 项）

A) 确认，进入文档写入和开发
B) 整体方向需要调整（说明哪里不对）
C) 细节需要修改（指出具体项）
D) 需要看完整文档再决定
```

如果用户选 D，输出完整的 Feature Spec 文本。

**⚠️ 铁律：用户未确认 Feature Spec 前，不得进入第4步，不得写入任何文件。**

---

## 第3.6步：生成/更新项目 CLAUDE.md

**首次运行时**（项目根目录不存在 CLAUDE.md）：
1. 读取 [references/project-claude-md-template.md](references/project-claude-md-template.md)
2. 填充项目名称、文档路径等变量
3. 写入 `{项目根目录}/CLAUDE.md`

**已有 CLAUDE.md 时**：
1. 读取现有内容
2. 检查是否已包含 `## Forge 工作流` 章节
3. 如果没有，在文件末尾追加 Forge 章节（不覆盖已有内容）
4. 如果已有，跳过（不重复写入）

---

## 第4步：写入文档（用户确认后执行）

**前提：用户已在第3步确认变更清单，且在第3.5步确认 Feature Spec。** 确认后一次性产出并写入以下内容：

### A. 更新 CHANGELOG

在 CHANGELOG 文件中追加本次变更记录（如果 CHANGELOG 不存在，新建并基于 git history 回溯生成历史记录）。

参考格式见 [references/prd-template.md](references/prd-template.md) 的 CHANGELOG 格式部分。

每条变更记录包含：
- **时间戳**：精确到日期
- **变更背景**：为什么要做这次变更
- **用户原始需求**：用户的原话或需求描述
- **设计方案**：采用的方案摘要
- **关键决策表**：议题 / 决定 / 原因
- **影响范围**：新增、修改、删除了什么

### B. 更新 PRD 正文

1. **更新头部元信息**：版本号递增、日期、状态
2. **更新迭代摘要区**（PRD 头部，保留所有版本）：
   - 新增本次版本的摘要条目
   - 每个版本列：版本号、日期、核心变更点、对应 CHANGELOG 条目定位
3. **更新功能章节**：
   - 新增功能 → 加入对应章节，标记 `[vX.Y 新增]`
   - 修改功能 → 原位更新，标记 `[vX.Y 修改]`
   - 砍掉的功能 → 移除或标记为已废弃
   - 需修复的问题 → 使用 `[需修复]`、`[需改进]`、`[需修改]` 标记
4. **写入 Feature Spec 章节**：将第3.5步用户确认的 Feature Spec 写入对应功能章节之后
5. **更新数据模型**：如涉及表结构或 API 变更
6. **更新已知问题/改进计划**：移除已解决的、新增发现的
7. **更新技术约束**：如有新约束
8. **更新交互流程图**：如交互有变
9. **更新附录修改清单**：按优先级列出所有需执行的修改
10. **自洽性检查**：确保 PRD 内各章节之间不矛盾（包括 Feature Spec 与功能描述的一致性）

### C. 产出迭代交付说明

在 PRD 的「本次迭代摘要」中包含面向下游 Agent 的交付说明：

- **变更摘要**（3-5行）
- **关键流程变化**（如有流程图则更新）
- **前端变更要点**：涉及哪些页面/组件、交互变化、视觉变化
- **后端变更要点**：涉及哪些 API/数据模型、逻辑变化
- **设计变更要点**：配色/布局/组件样式变化（如适用）
- **测试验收标准**：每个变更点对应的验收条件
- **Agent 补充信息**：
  - 受影响的文件路径提示（基于源码分析）
  - 数据库迁移注意事项（如涉及 schema 变更）
  - 兼容性提醒（如涉及 API 变更对前端的影响）
  - 关联变更提示（改 A 可能需要同步改 B）

此部分内容在对话中与用户确认核心方向后，由 skill 补充 Agent 所需的技术细节，一并写入 PRD。

---

写入完成后，输出最终总结：
- 如果本次迭代变更较多（≥4项）或涉及多个模块 → 用 widget 渲染完成仪表盘（指标卡片 + 变更统计图）
- 简单迭代 → 文字总结即可，包含：项目名、版本变更、诊断层级、变更数、文件状态

---

## Feature 状态管理（.features/ 架构）

### 核心原则

**领域文档（PRD.md）只存内容，不存运行状态。** 运行状态写入独立的 `.features/` 目录，按 feature 隔离，支持多会话并行。

### 状态标记协议

| 标记 | 含义 |
|------|------|
| `[⏳ 待处理]` | 已规划，未开始 |
| `[🔄 进行中]` | 当前正在执行 |
| `[✅ 已完成]` | 执行完成 |
| `[❌ 失败]` | 执行失败，需干预 |
| `[⏸️ 暂停]` | 等待用户确认或外部依赖 |

### forge-prd 是 Feature 的创建者

forge-prd 在第0步中负责创建 `.features/{feature-id}/` 目录并注册到全局索引。

#### 第0步额外操作：创建 Feature

1. **生成 feature-id**：基于需求描述生成简短的 kebab-case ID（如 `dedup-optimization`、`channel-mgmt-v2`）

2. **创建目录和文件**：
   ```bash
   mkdir -p .features/{feature-id}
   ```

3. **创建 status.md**：
   ```markdown
   # Feature: {feature-id}
   ## 描述：{一句话需求描述}
   ## PRD 版本：vX.Y
   ## 创建时间：{ISO 8601}

   ## Pipeline
   | phase | status | skill | started | completed | note |
   |-------|--------|-------|---------|-----------|------|
   | prd | [🔄 进行中] | forge-prd | {时间} | — | 诊断阶段 |
   | design | [⏳ 待处理] | — | — | — | — |
   | eng | [⏳ 待处理] | — | — | — | — |
   | qa | [⏳ 待处理] | — | — | — | — |
   ```

4. **注册到 `_registry.md`**（不存在则新建）：
   ```markdown
   | feature-id | version | status | skill | heartbeat | branch | 描述 |
   |------------|---------|--------|-------|-----------|--------|------|
   | {id} | vX.Y | active | forge-prd | {时间} | {分支名} | {描述} |
   ```

5. **版本号预留**：读取 `_registry.md` 找最高版本号 → 预留下一个 → 写入注册表。版本号不回收。

#### 状态更新时机

1. **进入第1步时**：创建 `.features/{id}/` + status.md + 注册到 `_registry.md`，prd 行标记为 `[🔄 进行中]`
2. **等待用户确认时**：prd 行状态改为 `[⏸️ 暂停]`，更新 heartbeat
3. **第4步写入完成后**：prd 行状态改为 `[✅ 已完成]`，记录 completed 时间，更新 heartbeat
4. **失败/中断时**：prd 行状态改为 `[❌ 失败]`，note 填失败原因

#### Heartbeat 规则

每次写入 status.md 时，同步更新 `_registry.md` 中该 feature 的 heartbeat 字段。

### 跨 Agent 协作

- 其他 skill 通过读取 `.features/{id}/status.md` 的 Pipeline 表来感知 forge-prd 的状态
- forge-dev 启动时读取 `_registry.md`，如果某 feature 的 heartbeat 超过 30 分钟且 status 仍为 active，触发孤儿检测警告
- **领域文档（PRD.md）不含任何运行状态**，多个会话可以安全地并行操作不同 feature

---

## 完整性原则

- PRD 是给后续 agent（设计、开发、QA）看的，必须准确、完整、无歧义
- CHANGELOG 是给人和 agent 看的，需要记录决策上下文和"为什么"
- 宁可多问一个问题，不要假设用户意图
- 每个变更点都要有明确的「当前行为」和「目标行为」对比
- 用户描述的是症状，skill 要做的是诊断——找到根因，而非只处理表面
- 对于带前端的项目，PRD 应覆盖设计系统、配色方案、交互细节
- 对于纯后端项目，PRD 应覆盖 API 设计、数据模型、性能要求
- 如果认为需求不合理，直接反驳并给出替代方案

---

## 资源

- **PRD 模板与 CHANGELOG 格式**：[references/prd-template.md](references/prd-template.md)
- **Feature Spec 模板**：[references/feature-spec-template.md](references/feature-spec-template.md)
- **项目 CLAUDE.md 模板**：[references/project-claude-md-template.md](references/project-claude-md-template.md)