---
name: project-stage-detect
description: "自动分析项目状态、检测开发阶段、识别缺失项，并根据现有工件推荐后续步骤。"
argument-hint: "[可选: 角色过滤器，如 'programmer' 或 'designer']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash
---

# 项目阶段检测

本技能扫描你的项目以确定其当前开发阶段、工件的完整性以及需要关注的缺失项。特别适用于以下场景：
- 接手一个现有项目
- 入职一个代码库
- 里程碑前检查缺失项
- 了解 "我们现在在哪里？"

---

## 工作流

### 1. 扫描关键目录

分析项目结构和内容：

**设计文档**（`design/`）：
- 统计 `design/gdd/*.md` 中的 GDD 文件数
- 检查 game-concept.md、game-pillars.md、systems-index.md
- 如果 systems-index.md 存在，统计总系统数与已设计系统数
- 分析完整性（概述、详细设计、边缘情况等）
- 统计 `design/narrative/` 中的叙事文档数
- 统计 `design/levels/` 中的关卡设计数

**源代码**（`src/`）：
- 统计源文件数（与语言无关）
- 识别主要系统（包含 5 个以上文件的目录）
- 检查 core/、gameplay/、ai/、networking/、ui/ 目录
- 估算代码行数（大致规模）

**生产工件**（`production/`）：
- 检查是否有活跃的 Sprint 计划
- 查找里程碑定义
- 查找路线图文档

**原型**（`prototypes/`）：
- 统计原型目录数
- 检查是否有 README（已文档化 vs 未文档化）
- 评估原型是已归档还是活跃的

**架构文档**（`docs/architecture/`）：
- 统计 ADR (Architecture Decision Record，架构决策记录) 数量
- 检查是否有概述/索引文档

**测试**（`tests/`）：
- 统计测试文件数
- 估算测试覆盖率（粗略启发式）

### 2. 分类项目阶段

根据扫描的工件确定阶段。先检查 `production/stage.txt` —
如果存在，使用其值（来自 `/gate-check` 的显式覆盖）。否则，
使用以下启发式规则自动检测（从最高阶段向前检查）：

| 阶段 | 指标 |
|------|------|
| **概念** | 无游戏概念文档，处于头脑风暴阶段 |
| **系统设计** | 游戏概念存在，系统索引缺失或不完整 |
| **技术搭建** | 系统索引存在，引擎未配置 |
| **预制作** | 引擎已配置，`src/` 不到 10 个源文件 |
| **制作** | `src/` 有 10 个以上源文件，活跃开发中 |
| **打磨** | 仅限显式设置（由 `/gate-check` 制作 -> 打磨关卡设置） |
| **发布** | 仅限显式设置（由 `/gate-check` 打磨 -> 发布关卡设置） |

### 3. 协作式缺失项识别

**不要**只是列出缺失的文件。而是**提出澄清问题**：

- "我看到战斗代码（`src/gameplay/combat/`）但没有 `design/gdd/combat-system.md`。这是先做的原型，还是应该进行逆向文档化？"
- "你有 15 个 ADR 但没有架构概述。需要我创建一个来帮助新贡献者吗？"
- "`production/` 中没有 Sprint 计划。你在其他地方跟踪工作吗（Jira、Trello 等）？"
- "我发现有游戏概念但没有系统索引。你是否已经将概念拆解为各个独立系统，还是需要我运行 `/map-systems`？"
- "原型目录有 3 个项目没有 README。这些是实验，还是需要文档化？"

### 4. 生成阶段报告

使用模板：`.claude/docs/templates/project-stage-report.md`

**报告结构**：
```markdown
# 项目阶段分析

**日期**：[日期]
**阶段**：[概念/系统设计/技术搭建/预制作/制作/打磨/发布]

## 完整性概览
- 设计：[X%]（[N] 个文档，[缺失项]）
- 代码：[X%]（[N] 个文件，[系统]）
- 架构：[X%]（[N] 个 ADR，[缺失项]）
- 生产管理：[X%]（[状态]）
- 测试：[X%]（[覆盖率估算]）

## 识别的缺失项
1. [缺失项描述 + 澄清问题]
2. [缺失项描述 + 澄清问题]

## 推荐后续步骤
[根据阶段和角色按优先级排列的列表]
```

### 5. 角色过滤的推荐（可选）

如果用户提供了角色参数（例如 `/project-stage-detect programmer`）：

**程序员**：
- 专注于架构文档、测试覆盖率、缺失的 ADR
- 代码与文档的差距

**设计师**：
- 专注于 GDD 完整性、缺失的设计章节
- 原型文档化

**制作人**：
- 专注于 Sprint 计划、里程碑追踪、路线图
- 跨团队协调文档

**通用**（无角色）：
- 所有缺失项的全景视图
- 各领域最高优先级的项目

### 6. 写入前请求批准

**协作协议**：
```
我已经分析了你的项目。以下是我的发现：

[展示摘要]

识别的缺失项：
1. [缺失项 1 + 问题]
2. [缺失项 2 + 问题]

推荐后续步骤：
- [优先级 1]
- [优先级 2]
- [优先级 3]

可以将完整的阶段分析写入 production/project-stage-report.md 吗？
```

等待用户批准后再创建文件。

---

## 用法示例

```bash
# 通用项目分析
/project-stage-detect

# 程序员视角分析
/project-stage-detect programmer

# 设计师视角分析
/project-stage-detect designer
```

---

## 后续行动

生成报告后，建议相关的后续步骤：

- **有概念但没有系统索引？** -> `/map-systems` 拆解为系统
- **缺失设计文档？** -> `/reverse-document design src/[系统]`
- **缺失架构文档？** -> `/architecture-decision` 或 `/reverse-document architecture`
- **原型需要文档化？** -> `/reverse-document concept prototypes/[名称]`
- **没有 Sprint 计划？** -> `/sprint-plan`
- **接近里程碑？** -> `/milestone-review`

---

## 协作协议

本技能遵循协作设计原则：

1. **先提问**：对缺失项提问，不要假设
2. **提供选项**："需要我创建 X，还是在其他地方跟踪了？"
3. **用户决定**：等待指示
4. **展示草稿**：显示报告摘要
5. **获取批准**："可以写入 production/project-stage-report.md 吗？"

**绝不要**静默写入文件。**始终**先展示发现并询问再创建工件。