What Are Milestone Reviews and Sprint Retrospectives in Claude Code Game Studios

Milestone reviews and sprint retrospectives are automated slash-command skills that generate structured markdown reports to assess project health at milestone checkpoints and sprint boundaries.

In the Claude Code Game Studios (CCGS) repository, these project management ceremonies are implemented as first-class scripted skills rather than manual meeting agendas. Defined in the .claude/skills/ directory, these automation tools analyze production data from multiple sources to produce consistent, data-driven assessments of development progress, complete with go/no-go recommendations for milestones and actionable improvement lists for sprints.

Milestone Reviews vs Sprint Retrospectives

While both skills follow similar execution pipelines, they serve different strategic purposes and produce distinct outputs.

Milestone reviews evaluate progress toward major project checkpoints (Alpha, Beta, etc.). They aggregate data from production/milestones/*.md, sprint reports in production/sprints/, the risk register at production/risk-register/, and code-health markers (TODO, FIXME, HACK). In full review mode, the skill spawns the PR-MILESTONE director gate to obtain a producer’s risk assessment before finalizing a GO/NO-GO recommendation. The output is written to production/milestones/[name]-review.md.

Sprint retrospectives focus on a single iteration’s performance. They analyze the specific sprint file (production/sprints/sprint-NNN.md), session logs in production/session-logs/, and prior retrospectives. No director gates are invoked—this is a pure self-reflection artifact. The skill generates a document at production/retrospectives/retro-[sprint-or-milestone].md containing three sections: What Went Well, What Didn’t, and Action Items.

Aspect	Milestone Review	Sprint Retrospective
Trigger	/milestone-review "alpha"	/retrospective sprint-005
Gate Interaction	Spawns PR-MILESTONE gate in full mode	No gates
Verdict	COMPLETE or BLOCKED	Always COMPLETE
Primary Output	Feature tables, risk assessment, go/no-go	Reflection sections, action items

How the Skills Work: Phase-Based Pipeline

According to the source specifications in .claude/skills/milestone-review/SKILL.md and .claude/skills/retrospective/SKILL.md, both skills execute a seven-phase pipeline using the allowed toolset (Read, Glob, Grep, Write, Task, AskUserQuestion).

1. Parse Arguments – Resolve the target (milestone name or sprint slug) and review mode (full|lean|solo for milestones).
2. Load Data – Glob and read relevant production files, including sprint data, session logs, and code-base health markers.
3. Analyze – Compute velocity metrics, risk assessments, code-health counts (TODO/FIXME tallies), and blocker lists.
4. Gate Interaction – (Milestone reviews only) If mode is full, spawn the PR-MILESTONE gate for producer input before finalizing the recommendation.
5. Present Draft – Display the compiled markdown document to the user.
6. User Confirmation – Prompt "May I write this to [file path]?" and write the file only on explicit approval.
7. Next-Step Handoff – Suggest subsequent commands such as /gate-check or /sprint-plan.

Running a Milestone Review

To assess progress toward a major checkpoint, invoke the skill with the milestone identifier:

/milestone-review "alpha"

The skill generates a comprehensive document including feature completeness tables, quality metrics, code-health counts, and risk assessments. As implemented in the repository, the output follows this structure:

# Milestone Review: Alpha

## Overview

- **Target Date**: 2025-10-01
- **Current Date**: 2025-09-20
- **Days Remaining**: 11
- **Sprints Completed**: 4/5

## Feature Completeness

### Fully Complete

| Feature | Acceptance Criteria | Test Status |
|---------|---------------------|-------------|
| Player Movement | All directions, variable speed | ✅ Passed |

## Code Health

- **TODO count**: 12
- **FIXME count**: 3

## Verdict

**GO** | *Rationale: Critical path features complete, acceptable technical debt levels.*

After presenting the draft, the skill asks: "May I write this to production/milestones/alpha-review.md?" If approved, the file is written and the skill returns VERDICT: COMPLETE. If declined, it returns VERDICT: BLOCKED.

Conducting a Sprint Retrospective

To analyze a completed sprint, use the retrospective command with the sprint identifier:

/retrospective sprint-005

As defined in .claude/skills/retrospective/SKILL.md, this analyzes the sprint file, session logs, and previous retrospectives to generate a structured reflection document:

# Sprint-005 Retrospective

## What Went Well

- 4 stories shipped on schedule.
- Session logs show smooth combat loop.

## What Didn't

- 1 story blocked (AI path-finding).
- 1 story deferred (new weapon art).

## Action Items

- Investigate AI blocker root cause (owner: gameplay-programmer, due: 2025-09-30).
- Schedule art review for deferred weapon (owner: art-director, due: 2025-10-05).

The skill prompts: "May I write this to production/retrospectives/retro-sprint-005.md?" Upon confirmation, it writes the file and concludes with VERDICT: COMPLETE. Unlike milestone reviews, retrospectives have no blocking state—their purpose is documentation and process improvement rather than gatekeeping.

Workflow Integration

These skills integrate directly into the CCGS development workflow as documented in docs/WORKFLOW-GUIDE.md. Lines 64-71 specify the sprint review step utilizing /retrospective, while lines 80-89 define the milestone review checkpoint using /milestone-review.

At predefined checkpoints (Alpha, Beta, Gold), producers run milestone reviews to obtain data-driven go/no-go decisions. At sprint boundaries, teams run retrospectives to capture lessons learned and generate concrete action items for process improvement.

Key Source Files and Architecture

Understanding these skills requires reference to specific implementation files:

• .claude/skills/milestone-review/SKILL.md – Full specification of the milestone review skill, including phase definitions, gate interaction logic, and verdict semantics.
• .claude/skills/retrospective/SKILL.md – Specification for the retrospective skill, defining the three-section output format and manual-input fallback procedures.
• CCGS Skill Testing Framework/skills/sprint/milestone-review.md – Test cases documenting expected behavior, edge cases, and mock data expectations.
• CCGS Skill Testing Framework/skills/sprint/retrospective.md – Test specification for retrospective generation, including data validation rules.
• docs/WORKFLOW-GUIDE.md – The overarching workflow document that places these commands in the context of the full production pipeline.

Summary

• Milestone reviews (/milestone-review) are gate-oriented assessments producing go/no-go recommendations for major checkpoints, with optional PR-MILESTONE director gate interaction in full mode.
• Sprint retrospectives (/retrospective) are reflection-oriented documents capturing lessons learned and action items without pass/fail gates.
• Both skills follow a seven-phase pipeline: parse, load, analyze, gate (milestone only), present, confirm, and handoff.
• Outputs are standardized markdown files written to production/milestones/ and production/retrospectives/ respectively.
• The skills are defined in .claude/skills/milestone-review/SKILL.md and .claude/skills/retrospective/SKILL.md, and integrated into the workflow guide at docs/WORKFLOW-GUIDE.md.

Frequently Asked Questions

What is the difference between a milestone review and a sprint retrospective?

A milestone review evaluates progress toward a major project checkpoint (like Alpha or Beta) and produces a GO/NO-GO recommendation, potentially blocking progress if risks are unacceptable. A sprint retrospective examines a single iteration to identify process improvements, generating action items without gatekeeping authority. Milestone reviews can trigger director gates; retrospectives cannot.

What data sources do these skills analyze?

Milestone reviews consume production/milestones/*.md definitions, sprint reports from production/sprints/, the risk register at production/risk-register/, and code-health markers (TODO, FIXME, HACK). Retrospectives focus on the specific sprint file (production/sprints/sprint-NNN.md), production/session-logs/, and historical retrospective data from production/retrospectives/.

Can I run a milestone review in different modes?

Yes. The milestone review skill supports three modes defined in .claude/skills/milestone-review/SKILL.md: full (spawns the PR-MILESTONE gate for producer assessment), lean (skips the gate, automated analysis only), and solo (minimal overhead for individual developers). Sprint retrospectives operate in a single mode.

Where are the generated reports stored?

Milestone reviews write to production/milestones/[name]-review.md, while sprint retrospectives write to production/retrospectives/retro-[sprint-or-milestone].md. Both skills prompt for explicit user confirmation before writing files and return a COMPLETE verdict upon successful write, or BLOCKED (milestones only) if the user declines.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}