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

> Learn about milestone reviews and sprint retrospectives, automated skills for assessing project health and driving continuous improvement at Claude Code Game Studios.

- Repository: [Donchitos/Claude-Code-Game-Studios](https://github.com/Donchitos/Claude-Code-Game-Studios)
- Tags: deep-dive
- Published: 2026-04-16

---

**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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/milestone-review/SKILL.md) and [`.claude/skills/retrospective/SKILL.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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:

```bash
/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:

```markdown

# 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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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:

```bash
/retrospective sprint-005

```

As defined in [`.claude/skills/retrospective/SKILL.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/retrospective/SKILL.md), this analyzes the sprint file, session logs, and previous retrospectives to generate a structured reflection document:

```markdown

# 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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/milestone-review/SKILL.md) and [`.claude/skills/retrospective/SKILL.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/retrospective/SKILL.md), and integrated into the workflow guide at [`docs/WORKFLOW-GUIDE.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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.