Back to Details

project-stage-detect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Stage Detection

项目阶段检测

This skill scans your project to determine its current development stage, completeness of artifacts, and gaps that need attention. It's especially useful when:
  • Starting with an existing project
  • Onboarding to a codebase
  • Checking what's missing before a milestone
  • Understanding "where are we?"
该技能会扫描你的项目，以确定其当前开发阶段、工件完整性以及需要关注的差距。在以下场景中尤其有用：
  • 接手现有项目时
  • 熟悉代码库时
  • 里程碑前检查缺失内容时
  • 想了解“我们进展到哪了”时

Workflow

工作流程

1. Scan Key Directories

1. 扫描关键目录

Analyze project structure and content:
Design Documentation (
design/
):
  • Count GDD files in 
    design/gdd/*.md
  • Check for game-concept.md, game-pillars.md, systems-index.md
  • If systems-index.md exists, count total systems vs. designed systems
  • Analyze completeness (Overview, Detailed Design, Edge Cases, etc.)
  • Count narrative docs in 
    design/narrative/
  • Count level designs in 
    design/levels/
Source Code (
src/
):
  • Count source files (language-agnostic)
  • Identify major systems (directories with 5+ files)
  • Check for core/, gameplay/, ai/, networking/, ui/ directories
  • Estimate lines of code (rough scale)
Production Artifacts (
production/
):
  • Check for active sprint plans
  • Look for milestone definitions
  • Find roadmap documents
Prototypes (
prototypes/
):
  • Count prototype directories
  • Check for READMEs (documented vs undocumented)
  • Assess if prototypes are archived or active
Architecture Docs (
docs/architecture/
):
  • Count ADRs (Architecture Decision Records)
  • Check for overview/index documents
Tests (
tests/
):
  • Count test files
  • Estimate test coverage (rough heuristic)
分析项目结构与内容：
设计文档 (
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/
):
  • 检查是否有活跃的冲刺计划
  • 查找里程碑定义文档
  • 寻找路线图文档
原型 (
prototypes/
):
  • 统计原型目录数量
  • 检查是否有README（已文档化vs未文档化）
  • 评估原型是已归档还是处于活跃状态
架构文档 (
docs/architecture/
):
  • 统计ADR（架构决策记录）数量
  • 检查是否有概述/索引文档
测试 (
tests/
):
  • 统计测试文件数量
  • 估算测试覆盖率（大致启发式评估）

2. Classify Project Stage

2. 分类项目阶段

Based on scanned artifacts, determine stage. Check 
production/stage.txt
first — if it exists, use its value (explicit override from 
/gate-check
). Otherwise, auto-detect using these heuristics (check from most-advanced backward):
StageIndicators
ConceptNo game concept doc, brainstorming phase
Systems DesignGame concept exists, systems index missing or incomplete
Technical SetupSystems index exists, engine not configured
Pre-ProductionEngine configured, 
src/
has <10 source files
Production
src/
has 10+ source files, active development
PolishExplicit only (set by 
/gate-check
Production → Polish gate)
ReleaseExplicit only (set by 
/gate-check
Polish → Release gate)
基于扫描到的工件确定阶段。优先检查
production/stage.txt
——若存在，则使用其值（来自
/gate-check
的显式覆盖）。否则，使用以下启发式规则自动检测（从最成熟阶段倒序检查）：
阶段指标
概念阶段无游戏概念文档，处于头脑风暴阶段
系统设计阶段存在游戏概念文档，系统索引缺失或不完整
技术搭建阶段存在系统索引，引擎未配置
预生产阶段引擎已配置，
src/
目录下源文件少于10个
生产阶段
src/
目录下有10个以上源文件，处于活跃开发状态
打磨阶段仅可手动设置（通过
/gate-check
从生产阶段切换至打磨阶段）
发布阶段仅可手动设置（通过
/gate-check
从打磨阶段切换至发布阶段）

3. Collaborative Gap Identification

3. 协作式差距识别

DO NOT just list missing files. Instead, ask clarifying questions:
  • "I see combat code (
    src/gameplay/combat/
    ) but no 
    design/gdd/combat-system.md
    . Was this prototyped first, or should we reverse-document?"
  • "You have 15 ADRs but no architecture overview. Should I create one to help new contributors?"
  • "No sprint plans in 
    production/
    . Are you tracking work elsewhere (Jira, Trello, etc.)?"
  • "I found a game concept but no systems index. Have you decomposed the concept into individual systems yet, or should we run 
    /map-systems
    ?"
  • "Prototypes directory has 3 projects with no READMEs. Were these experiments, or do they need documentation?"
请勿仅罗列缺失文件。相反，提出澄清问题：
  • “我看到了战斗代码(
    src/gameplay/combat/
    )，但未找到
    design/gdd/combat-system.md
    。是先做了原型，还是需要反向生成文档？”
  • “你有15份ADR，但没有架构概述文档。是否需要我创建一份以帮助新贡献者？”
  • “
    production/
    目录下无冲刺计划。你们是否在其他地方跟踪工作（如Jira、Trello等）？”
  • “我找到了游戏概念文档，但没有系统索引。你们是否已将概念分解为单个系统，还是需要运行
    /map-systems
    ？”
  • “原型目录有3个项目但无README。这些是实验项目，还是需要补充文档？”

4. Generate Stage Report

4. 生成阶段报告

Use template: 
.claude/docs/templates/project-stage-report.md
Report structure:
markdown
undefined
使用模板：
.claude/docs/templates/project-stage-report.md
报告结构:
markdown
undefined

Project Stage Analysis

项目阶段分析

Date: [date] Stage: [Concept/Systems Design/Technical Setup/Pre-Production/Production/Polish/Release] Stage Confidence: [PASS — clearly detected / CONCERNS — ambiguous signals / FAIL — critical gaps block progress]
日期: [date] 阶段: [概念阶段/系统设计阶段/技术搭建阶段/预生产阶段/生产阶段/打磨阶段/发布阶段] 阶段可信度: [通过——检测明确 / 存疑——信号模糊 / 未通过——关键差距阻碍进展]

Completeness Overview

完整性概述

  • Design: [X%] ([N] docs, [gaps])
  • Code: [X%] ([N] files, [systems])
  • Architecture: [X%] ([N] ADRs, [gaps])
  • Production: [X%] ([status])
  • Tests: [X%] ([coverage estimate])
  • 设计: [X%] ([N] 份文档，[差距项])
  • 代码: [X%] ([N] 个文件，[系统数])
  • 架构: [X%] ([N] 份ADR，[差距项])
  • 生产管理: [X%] ([状态])
  • 测试: [X%] ([覆盖率估算])

Gaps Identified

识别到的差距

  1. [Gap description + clarifying question]
  2. [Gap description + clarifying question]
  1. [差距描述 + 澄清问题]
  2. [差距描述 + 澄清问题]

Recommended Next Steps

推荐下一步操作

[Priority-ordered list based on stage and role]
undefined
[基于阶段和角色的优先级排序列表]
undefined

5. Role-Filtered Recommendations (Optional)

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

If user provided a role argument (e.g., 
/project-stage-detect programmer
):
Programmer:
  • Focus on architecture docs, test coverage, missing ADRs
  • Code-to-docs gaps
Designer:
  • Focus on GDD completeness, missing design sections
  • Prototype documentation
Producer:
  • Focus on sprint plans, milestone tracking, roadmap
  • Cross-team coordination docs
General (no role):
  • Holistic view of all gaps
  • Highest-priority items across domains
若用户提供了角色参数（如
/project-stage-detect programmer
）：
程序员:
  • 聚焦架构文档、测试覆盖率、缺失的ADR
  • 代码与文档的差距
设计师:
  • 聚焦GDD完整性、缺失的设计章节
  • 原型文档
制作人:
  • 聚焦冲刺计划、里程碑跟踪、路线图
  • 跨团队协调文档
通用（无角色）:
  • 所有差距的整体视图
  • 跨领域的最高优先级事项

6. Request Approval Before Writing

6. 写入前请求批准

Collaborative protocol:
I've analyzed your project. Here's what I found:

[Show summary]

Gaps identified:
1. [Gap 1 + question]
2. [Gap 2 + question]

Recommended next steps:
- [Priority 1]
- [Priority 2]
- [Priority 3]

May I write the full stage analysis to production/project-stage-report.md?
Wait for user approval before creating the file.
协作协议:
我已分析你的项目，以下是发现：

[展示摘要]

识别到的差距:
1. [差距1 + 问题]
2. [差距2 + 问题]

推荐下一步操作:
- [优先级1]
- [优先级2]
- [优先级3]

是否允许我将完整的阶段分析写入production/project-stage-report.md？
等待用户批准后再创建文件。

Example Usage

示例用法

bash
undefined
bash
undefined

General project analysis

通用项目分析

/project-stage-detect
/project-stage-detect

Programmer-focused analysis

面向程序员的分析

/project-stage-detect programmer
/project-stage-detect programmer

Designer-focused analysis

面向设计师的分析

/project-stage-detect designer

---
/project-stage-detect designer

---

Follow-Up Actions

后续操作

After generating the report, suggest relevant next steps:
  • Concept exists but no systems index? → 
    /map-systems
    to decompose into systems
  • Missing design docs? → 
    /reverse-document design src/[system]
  • Missing architecture docs? → 
    /architecture-decision
    or 
    /reverse-document architecture
  • Prototypes need documentation? → 
    /reverse-document concept prototypes/[name]
  • No sprint plan? → 
    /sprint-plan
  • Approaching milestone? → 
    /milestone-review
生成报告后，建议相关下一步操作：
  • 存在概念但无系统索引？ → 使用
    /map-systems
    将概念分解为系统
  • 缺失设计文档？ → 使用
    /reverse-document design src/[system]
  • 缺失架构文档？ → 使用
    /architecture-decision
    或
    /reverse-document architecture
  • 原型需要文档？ → 使用
    /reverse-document concept prototypes/[name]
  • 无冲刺计划？ → 使用
    /sprint-plan
  • 临近里程碑？ → 使用
    /milestone-review

Collaborative Protocol

协作协议

This skill follows the collaborative design principle:
  1. Question First: Ask about gaps, don't assume
  2. Present Options: "Should I create X, or is it tracked elsewhere?"
  3. User Decides: Wait for direction
  4. Show Draft: Display report summary
  5. Get Approval: "May I write to production/project-stage-report.md?"
Never silently write files. Always show findings and ask before creating artifacts.
该技能遵循协作设计原则：
  1. 先提问：询问差距相关问题，不做假设
  2. 提供选项：“我是否应该创建X，还是它在其他地方跟踪？”
  3. 用户决策：等待用户指示
  4. 展示草稿：显示报告摘要
  5. 获取批准：“是否允许我写入production/project-stage-report.md？”
切勿静默写入文件。务必先展示发现并在创建工件前征得同意。