project-stage-detect skill

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

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolve_config --keys workflow,automation

Automation mode: Resolve modes.automation (project.local.yaml → project.yaml → default collaborative). Every AskUserQuestion call and every file write follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automationalwaysask categories always prompt).

Resolved above — use as-is. No block → defaults in .claude/docs/config-resolution.md.

Resolve the tier — do not assume it. Saying "surface gaps per the resolved workflow

tier" without resolving it — no bootstrap, no helper call — leaves

the tier as whatever the model assumed. The tier decides what counts as a gap

at all: at full every missing doc is one; at minimal none of them are,

because a brief plus an engine is the normal state and code is the expected

next step. Guessing high tells a jam project it is missing GDDs, an art bible

and ADRs — the exact "process feels mismatched to my project" experience

modes.rigor exists to prevent. A missing bootstrap is invisible to a static

read — the config block simply does not render — so verify it by running.

workflow (per .claude/docs/workflow-modes.md). The tier governs which absent documents count as gaps (step 3) — below full, optional docs are not flagged.

1. Scan Key Directories

Start with the deterministic pass — it answers "what exists" for every catalogued artifact in one call:

Bash: bash .claude/scripts/artifact-check.sh

With no --phase it reports every phase, so a single call covers the whole project: per step, PRESENT / ABSENT / SHORT (with count= and min=) / PATTERNMISS / NOCHECK. Use it instead of hand-globbing each artifact below, and treat its NO_CHECK total as the honest bound on what existence checks can tell you.

It reports observations only — this skill still decides what stage those observations imply, and the tier still governs which absences are gaps at all (see the workflow-tier note below).

Then analyze what the script cannot: content quality, counts it does not track, and the judgement calls.

Design Documentation (design/):

• Count GDD files in design/gdd/*.md
• Check for game-concept.md (or design/game-brief.md at minimal), 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 (the code root — src/ Godot, Assets/ Unity, Source/ Unreal; resolve per .claude/docs/code-root-resolution.md):

• 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)

2. Classify Project Stage

Based on scanned artifacts, determine stage. Check project.stage in project.yaml first (if present); else production/stage.txt (legacy fallback) — either is an explicit override from /gate-check. Otherwise, auto-detect using these heuristics (check from most-advanced backward):

Always run the heuristics, even when a stage is configured — then COMPARE.

The configured value is authoritative for what the stage is; it is not

evidence that the artifacts support it. Report both, and when they disagree say

so explicitly:

> "Configured stage: Release. Observed artifacts indicate

> Pre-Production (2 source files, 0 ADRs, no architecture doc, no epics).

> These disagree — the configured stage may be stale, or work exists outside

> this repo."

Reading config and reporting it back is not detection. This skill's own

description promises "analyze project state, detect stage", and a stage

detector that cannot contradict its input is the one thing it must never be.

Observed live: it reported Release for a project whose artifacts matched its

own Pre-Production row, four stages below, and said nothing.

3. Collaborative Gap Identification

Surface gaps per the resolved workflow tier:

missing critical (Foundation-layer) ADRs. Do NOT flag an absent art bible unless visual-asset stories exist, and do NOT flag non-core UX specs.

• full — flag every missing doc type (GDDs, art bible, UX specs, ADRs) as a gap.
• standard — flag only required docs: missing GDDs for built systems and

absent GDDs, art bible, UX specs, or ADRs as gaps; the expected next step is code.

• minimal — a design/game-brief.md + engine present is the normal state. Do NOT flag

DO NOT just list missing files. Instead, ask clarifying questions (only for gaps the tier above says to surface):

• "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?"

4. Generate Stage Report

Use template: .claude/docs/templates/project-stage-report.md