Pm Docs

---
name: pm-docs
description: |
  Use when: 需要输出PRD/BRD/MRD产品文档、方案文档、商业计划文档、需要文档模板
  Do NOT auto-select when: 用户用自然语言说"写需求文档""写PRD""帮我设计需求"等新产品请求
    → 这些必须先路由到 start-super-pm
  Direct slash-command use is allowed: 用户显式输入 /pm-docs 时可直接进入，但必须通过本 skill 的前置门禁
  Do NOT use when: 文档已完备无需生成、仅需口头讨论无需书面输出
allowed-tools:
  - Read
  - Write
  - AskUserQuestion
  - Agent
  - Bash
---

## Preamble (run first)

```bash
# 检查前置文档
echo "📊 正在检查前置文档..."

if [ -f "docs/01-需求调研/MVP方案.md" ]; then
  echo "✅ MVP方案 - 已找到"
else
  echo "⏳ MVP方案 - 未找到"
fi

if [ -f "docs/01-需求调研/需求调研报告.md" ]; then
  echo "✅ 需求调研报告 - 已找到"
else
  echo "⏳ 需求调研报告 - 未找到"
fi

if [ -f "docs/01-需求调研/市场调研报告.md" ]; then
  echo "✅ 市场调研报告 - 已找到"
else
  echo "⏳ 市场调研报告 - 未找到"
fi
```

---

## 写入时边界

只讨论时不写文件，启动检查不创建目录。用户要求保存产物时，先确认当前产品、精确输出路径及已有文件的覆盖/追加选择；确认后**仅在实际 Write 前**创建该输出文件的父目录。完整安装可参见 `skills/_shared/artifact-policy.md`，单独安装本 skill 也按本段执行。

---

## 前置门禁

无论从哪个入口进入，都必须执行前置文档检查：

1. 检查 `docs/01-需求调研/` 中是否有 **MVP方案**（黄金路径的必要前置）
2. 如果有 MVP方案 → 读取文档，判断是否与当前用户描述的产品相关
   - 相关 → 前置已满足，继续执行
   - 不相关 → 停止，建议先完成前置流程
3. 如果没有 MVP方案 → 停止，建议先执行 `/pm-brainstorm` → `/pm-demand` → `/pm-mvp`

不得在门禁不满足时生成文档。

---

## 跨 Agent 交互规则

当流程要求与用户交互时：

1. 如果当前环境支持 AskUserQuestion，使用 AskUserQuestion（最佳体验）。
2. 如果当前环境不支持 AskUserQuestion，必须用普通聊天消息提出同样问题。
3. 一次只问一个问题。
4. 提问后必须停止当前回合，等待用户回答（STOP and WAIT）。
5. 不得在用户回答前生成文档、写入 docs。
6. 已有 docs 文件不能替代本轮用户回答。

---

产出要求：关键功能引用已确认的需求或 MVP 条目；标记证据、假设和待决策问题，并为功能写出可验证的验收标准。不要凭空补齐未经确认的用户或数据。

## 执行流程


### 步骤 1: 确定文档类型（主 agent - 用户交互）

使用 AskUserQuestion 询问：

> 您希望生成哪些文档？
>
> A) 仅 PRD - 产品需求文档
> B) 仅 BRD - 商业需求文档
> C) 仅 MRD - 市场需求文档
> D) PRD + BRD + MRD（全套文档，推荐）
> E) 让我推荐（根据项目状态自动选择）
>
> 💡 提示：选择"D"可并行生成全套文档，效率提升 3x

用户选择后，记录到变量 `DOC_TYPES`（数组）

---

### 步骤 2: 读取前置数据（主 agent）

**读取所有可能需要的前置文档**：

```bash
# 主 agent 一次性读取所有前置文档
required_docs=(
  "docs/01-需求调研/MVP方案.md"
  "docs/01-需求调研/需求调研报告.md"
  "docs/01-需求调研/市场调研报告.md"
  "docs/01-需求调研/确认需求清单.md"
  "docs/01-需求调研/优先级排序报告.md"
)

for doc in "${required_docs[@]}"; do
  if [ -f "$doc" ]; then
    # 使用 Read 工具读取
    echo "读取 $doc"
  fi
done
```

**构建上下文摘要**（避免占用大量上下文）：

提取关键信息：
- 产品名称
- 目标用户
- 核心功能
- MVP范围
- 市场数据
- 商业目标

**将关键信息存储为结构化数据**，准备传递给 subagent。

---

### 步骤 3: 并行派发 subagent 生成文档（核心优化）

**优化说明**：
- 主 agent 一次性派发多个 subagent
- 每个 subagent 负责生成一个文档
- 文档生成细节不占用主 agent 上下文
- 所有文档并行生成

---

#### 3.1 构建 subagent 任务

**如果用户选择"全套文档"**：

准备 3 个并行 subagent 任务：

```json
[
  {
    "task_id": "generate_prd",
    "doc_type": "PRD",
    "required_data": [
      "产品名称",
      "目标用户",
      "MVP功能列表",
      "用户需求",
      "优先级排序"
    ]
  },
  {
    "task_id": "generate_brd",
    "doc_type": "BRD",
    "required_data": [
      "产品名称",
      "商业模式",
      "市场数据",
      "成本分析",
      "盈利预测"
    ]
  },
  {
    "task_id": "generate_mrd",
    "doc_type": "MRD",
    "required_data": [
      "产品名称",
      "市场调研数据",
      "用户画像",
      "竞品分析",
      "市场机会"
    ]
  }
]
```

---

#### 3.2 使用 Agent 工具并行派发

**并行派发 3 个 subagent**（关键优化）：

```
# 同时启动 3 个 subagent
使用 Agent 工具，参数：

Agent 1:
  subagent_type: "general-purpose"
  description: "生成 PRD 文档"
  prompt: |
    你是一个产品文档专家。请生成 PRD（产品需求文档）。

    **输入数据**：
    {从步骤2提取的关键信息}

    **要求**：
    1. 使用 Write 工具生成文档到 `docs/02-方案设计/PRD产品需求文档.md`
    2. 包含以下章节：
       - 产品概述
       - 目标用户
       - 功能需求（基于MVP方案）
       - 非功能需求
       - 交互流程
       - 数据埋点
    3. 基于前置数据填充内容，不要虚构
    4. 标注数据来源

    **输出**：返回生成的文档路径

Agent 2:
  subagent_type: "general-purpose"
  description: "生成 BRD 文档"
  prompt: |
    你是一个商业分析专家。请生成 BRD（商业需求文档）。

    **输入数据**：
    {从步骤2提取的关键信息}

    **要求**：
    1. 使用 Write 工具生成文档到 `docs/02-方案设计/BRD商业需求文档.md`
    2. 包含以下章节：
       - 商业目标
       - 商业模式
       - 盈利方式
       - 成本分析
       - 收益预测
    3. 基于前置数据填充内容

    **输出**：返回生成的文档路径

Agent 3:
  subagent_type: "general-purpose"
  description: "生成 MRD 文档"
  prompt: |
    你是一个市场分析专家。请生成 MRD（市场需求文档）。

    **输入数据**：
    {从步骤2提取的关键信息}

    **要求**：
    1. 使用 Write 工具生成文档到 `docs/02-方案设计/MRD市场需求文档.md`
    2. 包含以下章节：
       - 市场概述
       - 用户画像
       - 竞品分析
       - 市场机会
       - 进入策略
    3. 基于市场调研数据填充

    **输出**：返回生成的文档路径
```

**主 agent 等待所有 subagent 完成**。

---

### 步骤 4: 收集结果并验证（主 agent）

**主 agent 收集所有 subagent 的返回结果**：

```json
{
  "generated_docs": [
    {
      "doc_type": "PRD",
      "path": "docs/02-方案设计/PRD产品需求文档.md",
      "status": "success",
      "size": "15KB"
    },
    {
      "doc_type": "BRD",
      "path": "docs/02-方案设计/BRD商业需求文档.md",
      "status": "success",
      "size": "12KB"
    },
    {
      "doc_type": "MRD",
      "path": "docs/02-方案设计/MRD市场需求文档.md",
      "status": "success",
      "size": "10KB"
    }
  ]
}
```

**验证文档**：
- 检查文件是否存在
- 检查文件大小是否合理
- （可选）读取文档开头验证格式

---

### 步骤 5: 生成汇总报告（主 agent）

使用 Write 工具生成汇总报告：

```markdown
# 文档生成报告

## 生成概况

**生成时间**: {时间}
**文档数量**: 3 个
**总耗时**: {并行执行时间}

## 文档清单

### 1. PRD - 产品需求文档
- **路径**: docs/02-方案设计/PRD产品需求文档.md
- **大小**: 15KB
- **状态**: ✅ 生成成功
- **包含章节**: 产品概述、目标用户、功能需求、非功能需求、交互流程、数据埋点

### 2. BRD - 商业需求文档
- **路径**: docs/02-方案设计/BRD商业需求文档.md
- **大小**: 12KB
- **状态**: ✅ 生成成功
- **包含章节**: 商业目标、商业模式、盈利方式、成本分析、收益预测

### 3. MRD - 市场需求文档
- **路径**: docs/02-方案设计/MRD市场需求文档.md
- **大小**: 10KB
- **状态**: ✅ 生成成功
- **包含章节**: 市场概述、用户画像、竞品分析、市场机会、进入策略

## 数据来源

- MVP方案
- 需求调研报告
- 市场调研报告
- 优先级排序报告

## 下一步建议

建议执行：
1. /pm-proto - 基于PRD设计原型
2. /pm-tech - 基于PRD对接技术方案
3. /pm-data - 设计数据指标体系
```

---

## 对比：优化前 vs 优化后

### 优化前（pm-docs v1）

```
主 agent 执行流程：
1. 询问用户（10 tokens）
2. 读取前置数据（200 tokens）
3. 生成 PRD（3000 tokens 内容）
4. 生成 BRD（2500 tokens 内容）
5. 生成 MRD（2000 tokens 内容）
6. 生成汇总（100 tokens）

总计：7810 tokens
耗时：串行执行，约 10-15 分钟
上下文占用：文档内容全量占用
```

### 优化后（pm-docs-v2）

```
主 agent 执行流程：
1. 询问用户（10 tokens）
2. 读取前置数据（200 tokens）
3. 派发 3 个 subagent（50 tokens）
   ├─ Subagent 1: 生成 PRD（不占用主 agent）
   ├─ Subagent 2: 生成 BRD（不占用主 agent）
   └─ Subagent 3: 生成 MRD（不占用主 agent）
4. 接收结果（150 tokens 结构化数据）
5. 生成汇总（100 tokens）

总计：510 tokens
耗时：并行执行，约 3-5 分钟
效率提升：93% token 节省，3x 速度提升
```

---

## 关键优化点

### 1. 并行执行
```
v1: PRD → BRD → MRD（串行）
v2: PRD
    ├─ BRD  （并行）
    └─ MRD
```

### 2. 上下文节省
- ✅ 文档内容不占用主 agent 上下文
- ✅ 主 agent 只处理文档路径和元数据
- ✅ Token 使用减少 93%

### 3. 异常处理

**如果某个 subagent 失败**：
1. 主 agent 检测到失败
2. 提供选项：
   - A) 重试失败的文档
   - B) 手动补充
   - C) 跳过该文档
3. 继续处理其他成功的文档

---

## 注意事项

### 何时使用并行模式

✅ **适合并行**：
- 生成多个文档（PRD + BRD + MRD）
- 文档之间相对独立
- 有充足的前置数据

❌ **不适合并行**：
- 只生成单个文档
- 文档之间强依赖（如 PRD 依赖 BRD 的结果）
- 前置数据缺失

### 单文档模式

如果用户只选择生成一个文档：
- 使用单个 subagent 执行
- 仍然节省上下文（文档内容不占用主 agent）

---

## 版本说明

**v2.0.0** - Subagent 架构重构
- 新增 Agent 工具支持
- 文档生成并行化
- 主 agent 上下文优化 93%
- 效率提升 3x

**v1.0.0** - 初始版本
- 基础文档生成功能
- 串行执行

---

## 输出质量对比

**✅ Good 示例**：
```
- 有数据引用：「根据 Q4 数据，留存率从 35% 降至 28%」
- 有验证来源：「数据来源：Google Analytics, 2025-12-01」
- 有明确建议：「建议将新手引导步骤从 5 步减少至 3 步」
```

**❌ Bad 示例**：
```
- 模糊结论：「数据表明留存率有所下降」
- 无来源：「根据经验，这个功能很重要」
- 没有行动建议：「留存是个问题」
```

---

## 常见误区 / Red Flags — STOP

出现以下情况立即停止并回溯：

| 误区 | 正确做法 |
|------|---------|
| 使用"应该"、"大概"、"看起来"做结论 | 必须基于实际数据和验证 |
| 未运行检查就声称已完成 | 先验证，再陈述 |
| 因时间紧迫跳过关键步骤 | 没有例外，时间紧更要严格 |
| "这次应该没问题"的想法 | 每次都要重新验证 |

---

## 产出质量检查 / Verification Checklist

- [ ] 前置依赖已满足（输入文档/数据已收集）
- [ ] 核心步骤已全部执行
- [ ] 输出文档已生成到 `docs/` 目录
- [ ] 每个判断都有数据/证据支撑
- [ ] 已推荐 2-3 个后续 skill

> ⚠️ 任何一项未通过 → 补全后再标记完成。

---