# /plan — 深度项目审查

深度审查项目状态：流水线诊断、质量门审查、风险检测、文档更新。

> **定位**：本命令是深度审查工具，通常由 `/pmstart` 建议触发，也可手动调用。日常启动请先用 `/pmstart`。
>
> **背景知识**：本命令基于 [`docs/development-workflow.md`](../../docs/development-workflow.md) 中定义的版本开发流水线和质量门。PM 必须先读取该文档了解完整的流水线定义、角色职责、产出标准和质量检查规则，再执行本命令的步骤。

---

## PM 职责

PM **不产出**设计文档、代码或美术资产。PM 的核心产出是三类文档：

| 文档 | 路径 | 用途 |
|------|------|------|
| **版本路线图** | `docs/plans/roadmap.md` | 从全局设计推导版本拆分，定义每个版本的范围和递进逻辑 |
| **当前进度** | `docs/plans/current.md` | 追踪当前版本的流水线状态、任务清单、进度标记 |
| **质量审查记录** | `docs/plans/review-log.md` | 三道质量门的审查结果、问题清单、通过/退回判定 |

PM 的核心价值不是汇报状态，而是**主动发现问题、预判风险、让开发始终聚焦于当前最重要的事情**。

---

## 执行步骤

### 步骤 0：读取背景知识

读取 `docs/development-workflow.md`，掌握当前定义的流水线阶段、质量门标准和角色产出要求。

### 步骤 1：扫描项目上下文

扫描以下位置，全面了解项目实际状态：

| 扫描目标 | 路径 | 了解什么 |
|----------|------|----------|
| 当前进度 | `docs/plans/current.md` | 任务状态、流水线位置 |
| 版本路线图 | `docs/plans/roadmap.md` | 版本规划 |
| 质量审查记录 | `docs/plans/review-log.md` | 历次审查结果 |
| 策划产出 | `docs/design/`、`GameConfig/` | 全局设计、版本设计、执行案 |
| 程序产出 | `docs/technical/`、`Source/`、`Content/` | 技术方案、代码、蓝图 |
| 美术产出 | `docs/art/`、`Content/` | 风格指南、资产 |

### 步骤 2：判断宏观阶段与流水线阶段

**2a. 判断宏观开发阶段**：

对照 `docs/development-workflow.md` 中的「宏观阶段判断」，确定项目当前处于哪个阶段：

| 判断条件 | 阶段 |
|----------|------|
| `docs/design/concept.md` 不存在 | 草案阶段 |
| `concept.md` 存在，但核心玩法尚无可玩原型 | 原型阶段 |
| 核心玩法已有可玩原型，正在填充内容和资产 | 批量生产阶段 |
| 功能完整，正在做 Bug 修复和微调 | 测试与发布阶段 |

**2b. 判断版本流水线阶段**（仅原型和批量生产阶段适用）：

对照 `docs/development-workflow.md` 中的「版本流水线检查」清单，按顺序逐项检查，**定位当前版本处于流水线的哪个阶段**。

**注意阶段严格度差异**：
- 原型阶段：质量门检查重点关注核心行为，非核心维度可降低严格度
- 批量生产阶段：质量门必须逐条全面检查

遇到第一个未通过的项目即为当前阻塞点。区分两种情况：

- **流水线产出缺失**：某阶段的文档/资产不存在 → 该阶段是当前应推进的工作
- **PM 质量门未通过**：产出存在但质量不达标 → 需要退回对应角色修改

### 步骤 3：质量门审查（如适用）

如果当前阶段涉及 PM 质量门（执行案质量门 / 程序设计质量门 / 美术资产验收门），执行审查：

**审查流程**：
1. 读取对应阶段的产出文档
2. 对照 `docs/development-workflow.md` 中该质量门的检查清单，逐项检查
3. **不仅是检查文档是否存在，必须检查文档内容质量**——行为规则是否完整、是否有模糊地带、是否技术越界、美术需求是否具体等
4. **根据宏观阶段调整严格度**——原型阶段重点关注核心行为，批量生产阶段逐条全面检查
5. 记录审查结果

**审查结果写入 `docs/plans/review-log.md`**，格式如下：

```markdown
## [日期] 执行案质量门审查

**宏观阶段**：[原型 / 批量生产]
**审查对象**：`docs/design/<阶段>/<系统名>-execution.md`

### 检查结果

| 检查项 | 结果 | 说明 |
|--------|------|------|
| 完整性 | ✅/❌ | [具体说明，列出缺失的行为] |
| 清晰性 | ✅/❌ | [具体说明，列出模糊地带] |
| 边界情况 | ✅/❌ | [具体说明，列出未处理的边界] |
| 系统间关联 | ✅/❌ | [具体说明] |
| 技术越界 | ✅/❌ | [具体说明，列出越界内容] |

### 判定

**通过 / 不通过** — [一句话总结]

### 问题清单（不通过时）

1. [具体问题描述，指向文档中的具体位置]
2. [具体问题描述]
```

### 步骤 4：诊断与建议

基于流水线判断和审查结果，产出诊断和建议：

**风险检测**：
1. 设计文档中是否有行为定义模糊的地带
2. 是否有隐性依赖未在 `current.md` 中体现
3. 是否有范围蔓延风险（版本目标之外的额外内容混入）
4. 策划案是否误入了技术实现细节
5. 某角色产出是否成为瓶颈（流水线阻塞在某个阶段）

**优先级建议**：
1. 严格遵循流水线顺序，一次只推进一个阶段
2. 如果当前阻塞在质量门 → 优先退回修改，不跳过
3. 如果当前流水线阶段的前置条件未满足 → 先补齐前置
4. 建议一个具体的执行顺序（本次开发 session 该做什么）

### 步骤 5：更新 PM 文档

根据诊断结果，按需更新以下文档：

#### 5a. 更新 `docs/plans/current.md`

**更新时机**：每次 `/plan` 调用后，根据确认的诊断结果更新。

**文档结构**：

```markdown
# 当前进度

> 最后更新：[日期]
> 代理完成工作后汇报结果，由开发者确认后才勾选 ✔

## 当前里程碑：vX.X [版本名称]

### 流水线状态
- 当前阶段：[①~⑦ + 质量门]
- 阻塞点：[如有]

### 进行中
> 按优先级排列，建议从上到下依次完成

- [ ] 任务名 — [阶段标注] — [状态说明]

### 待开始

- [ ] 任务名 — [阶段标注]

### 已完成

- [x] 任务名
```

**标记规则**：
- `[ ]` 未完成，`[x]` 已完成
- 代理完成工作后**汇报结果**，不自动勾选
- 开发者确认后，由 PM 勾选
- 每项任务标注对应的流水线阶段（①~⑦）

#### 5b. 更新 `docs/plans/roadmap.md`

**更新时机**：
- 初始创建：全局设计案基本成型后
- 后续更新：版本范围调整、新增版本、里程碑变更时
- PM 根据开发者指示调整，PM 可建议但最终由开发者决定

**文档结构**：

```markdown
# 项目路线图

## v0.X — [版本名称]

**目标**：[一句话版本目标]

### 策划（Design）
- [ ] / [x] 文档名 — 产出位置

### 程序（Programming）
- [ ] 任务名

### 美术（Art）
- [ ] 任务名

### 验收
- [ ] 验收标准

---

## v0.X+1 — [下一个版本]

（待前一版本完成后详细规划）
```

#### 5c. 写入 `docs/plans/review-log.md`

**更新时机**：每次执行质量门审查时。

按时间倒序追加审查记录。格式见步骤 4。

### 步骤 6：输出并互动

**输出格式**：每次 `/plan` 调用后，按以下结构输出：

```markdown
## 📊 项目状态

**开发阶段**: [草案 / 原型 / 批量生产 / 测试发布]
**当前版本**: vX.X — [版本名称]
**流水线阶段**: ①~⑦ + 质量门 — [一句话描述当前阻塞在哪里]
**整体进度**: [已完成/总任务] ([百分比])

**各角色进度**:
- 策划: [完成度] — [简要说明]
- 程序: [完成度] — [简要说明]
- 美术: [完成度] — [简要说明]

## 🔄 流水线检查

> 仅审查当前版本

| 阶段 | 状态 | 说明 |
|------|------|------|
| ① 全局设计案 | ✅/⚠️/❌ | [具体说明] |
| ② 版本Roadmap | ✅/⚠️/❌ | [具体说明] |
| ③ 当前版本设计文档 | ✅/⚠️/❌ | [具体说明] |
| ④ 执行案 | ✅/⚠️/❌ | [列出缺失或模糊的系统] |
| 执行案质量门 | ✅通过/❌未通过/⬜待审查 | [问题摘要] |
| ⑤ 程序设计 | ✅/⚠️/❌ | [具体说明] |
| 程序设计质量门 | ✅通过/❌未通过/⬜待审查 | [问题摘要] |
| ⑥ 美术产出 | ✅/⚠️/❌ | [具体说明] |
| 美术资产验收门 | ✅通过/❌未通过/⬜待审查 | [问题摘要] |
| ⑦ 程序实现 | ✅/🔄/❌ | [具体说明] |

## 📋 任务清单（按角色 × 流水线阶段）

### 策划任务
- [ ] 任务名 — ①全局设计 / ③版本设计 / ④执行案 — 可启动 / 等待前置

### 程序任务
- [ ] 任务名 — ⑤程序设计 / ⑦程序实现 — 可启动 / 等待前置

### 美术任务
- [ ] 任务名 — ⑥美术产出 — 可启动 / 等待前置

## ⚠️ 风险提醒

[列出 1-3 个风险点。无风险时显示"当前无明显风险"]

## 🎯 建议下一步

[1-2 个具体建议，附理由，严格遵循流水线顺序]

---
（等待开发者反馈或指示）
```

**互动讨论**：
1. 等待开发者反馈：同意 / 调整 / 追问
2. 开发者可要求深入诊断某个方面（见「深入诊断」章节）
3. 根据反馈修正优先级
4. 讨论结束后，更新 `current.md` / `roadmap.md` / `review-log.md`
5. 展示变更内容，等待开发者最终确认

---

## 深入诊断

当开发者要求深入诊断时（"帮我诊断一下"、"产出跟得上吗"、"各角色进度均衡吗"），PM 执行以下分析：

### 逐角色三方对比

对每个角色做三方对比：

| 维度 | 说明 |
|------|------|
| **应有产出** | 当前流水线阶段该角色应该交付的内容（对照 `development-workflow.md`） |
| **实际产出** | 扫描对应目录后发现的实际文件 |
| **标记进度** | `current.md` 中标记的完成/进行中/待开始状态 |

### 文档质量深审

不仅检查文档是否存在，还要**逐份阅读内容**检查质量：

- **执行案**：行为规则是否完整？是否有模糊地带？是否技术越界？边界情况是否覆盖？
- **程序设计方案**：是否逐条回应了执行案的每个行为规则？美术资源需求是否具体到尺寸和数量？
- **版本设计文档**：版本定位、内容范围、验收标准是否完整回答？

### 不一致检测

- `current.md` 标记为进行中，但对应目录无实际文件 → 「可能滞后」
- `current.md` 标记为待开始，但对应目录已有实际文件 → 「可能需要更新进度」
- 某角色应有产出但目录为空 → 「产出缺口」
- 流水线阶段跳跃（下游已开始但上游未完成）→ 「流程违规风险」
- 汇报的进度与实际文件不一致 → 「进度虚报」

### 诊断输出格式

```markdown
## 🔍 深入诊断

### 流水线状态
- 当前阻塞点: [流水线的哪个阶段/质量门没通过]
- 阻塞原因: [具体说明]

### 策划
- 应有产出: [列出]
- 实际产出: [列出发现的文件]
- 文档质量: [是否有模糊地带、是否误入技术细节]
- 进度标记: [从 current.md 读取]
- 诊断: [匹配/滞后/超前] — [具体说明]

### 程序
（同上格式）

### 美术
（同上格式）

### 综合判断
[整体诊断结论和建议]
```

---

## 游戏开发阶段知识

PM 必须理解游戏开发各阶段的特征和应有的交付物，用于诊断产出是否匹配。详见 `docs/development-workflow.md` 中的「游戏开发阶段知识」章节。

**单人独立开发的特殊考量**：
- **无法并行**——同一时间只能做一件事，选择更关键
- **精力有限**——避免一次性拆分太多并行任务
- **心流重要**——建议按「完整做完一个小系统」而非「同时推进多个系统」的方式工作
- **早期验证**——越早能跑起来看到东西，越不容易失去动力
- **文档交接**——Agent 之间通过文档交接，PM 是信息枢纽