playtest-report

Phase 1: Parse Arguments

Resolve the review mode (once, store for all gate spawns this run):

1. If --review [full|lean|solo] was passed → use that
2. Else read production/review-mode.txt → use that value
3. Else → default to lean

See .claude/docs/director-gates.md for the full check pattern.

Determine the mode:

• new → generate a blank playtest report template
• analyze [path] → read raw notes and fill in the template with structured findings

Phase 2A: New Template Mode

Generate this template and output it to the user:

# Playtest Report

## Session Info
- **Date**: [Date]
- **Build**: [Version/Commit]
- **Duration**: [Time played]
- **Tester**: [Name/ID]
- **Platform**: [PC/Console/Mobile]
- **Input Method**: [KB+M / Gamepad / Touch]
- **Session Type**: [First time / Returning / Targeted test]

## Test Focus
[What specific features or flows were being tested]

## First Impressions (First 5 minutes)
- **Understood the goal?** [Yes/No/Partially]
- **Understood the controls?** [Yes/No/Partially]
- **Emotional response**: [Engaged/Confused/Bored/Frustrated/Excited]
- **Notes**: [Observations]

## Gameplay Flow
### What worked well
- [Observation 1]

### Pain points
- [Issue 1 -- Severity: High/Medium/Low]

### Confusion points
- [Where the player was confused and why]

### Moments of delight
- [What surprised or pleased the player]

## Bugs Encountered
| # | Description | Severity | Reproducible |
|---|-------------|----------|-------------|

## Feature-Specific Feedback
### [Feature 1]
- **Understood purpose?** [Yes/No]
- **Found engaging?** [Yes/No]
- **Suggestions**: [Tester suggestions]

## Quantitative Data (if available)
- **Deaths**: [Count and locations]
- **Time per area**: [Breakdown]
- **Items used**: [What and when]
- **Features discovered vs missed**: [List]

## Overall Assessment
- **Would play again?** [Yes/No/Maybe]
- **Difficulty**: [Too Easy / Just Right / Too Hard]
- **Pacing**: [Too Slow / Good / Too Fast]
- **Session length preference**: [Shorter / Good / Longer]

## Top 3 Priorities from this session
1. [Most important finding]
2. [Second priority]
3. [Third priority]

Phase 2B: Analyze Mode

Read the raw notes at the provided path. Cross-reference with existing design documents. Fill in the template above with structured findings. Flag any playtest observations that conflict with design intent.

Optional input: a recorded think-aloud session

Written notes lose the moment. When the tester can instead record the screen, talk while playing, and press one marker key whenever something catches, the raw notes become three files, and the analysis joins them on time:

Procedure:

1. Transcribe locally (e.g. faster-whisper — local, so no /api-cost-gate). With game audio under the voice, turn VAD off (vad_filter=False) and use medium or larger. The default VAD filter with small dropped the last ten minutes of a fifteen-minute StarDiver session (2026-10-01) because it classed speech over game sound as non-speech; rerunning with VAD off and medium recovered 87 lines.
2. Anchor the clocks. Take the recording's start time from ffprobe (format_tags.creation_time, UTC) and line it up with the state log. Check one marker against an event you can see on screen before trusting the rest.
3. Bundle per utterance and per marker: the transcript line, the frame at that time, and the state-log entries around it. Those bundles are the raw notes this mode then analyzes.

Before the build goes to the tester, press the marker key once and confirm the marker file appears. A StarDiver build shipped with a marker key that wrote nothing, and the session's markers were lost. This check belongs to whoever hands over the build, not to the analysis afterwards.

Phase 3: Action Routing

Categorize all findings into four buckets:

• Design changes needed — fun issues, player confusion, broken mechanics, observations that conflict with the GDD's intended experience
• Balance adjustments — numbers feel wrong, difficulty too spiked or too flat
• Bug reports — clear implementation defects that are reproducible
• Polish items — not blocking progress, but friction or feel issues for later

Present the categorized list, then route:

• Design changes: "Run /propagate-design-change [path] on the affected design document to find downstream impacts before making changes."
• Balance adjustments: "Run /balance-check [system] to verify the full balance picture before tuning values."
• Bugs: "Use /bug-report to formally track these."
• Polish items: "Add to the polish backlog in production/ when the team reaches that phase."

Phase 3b: Creative Director Player Experience Review

Review mode check — apply before spawning CD-PLAYTEST:

• solo → skip. Note: "CD-PLAYTEST skipped — Solo mode." Proceed to Phase 4 (save the report).
• lean → skip (not a PHASE-GATE). Note: "CD-PLAYTEST skipped — Lean mode." Proceed to Phase 4 (save the report).
• full → spawn as normal.

After categorising findings, spawn creative-director via Task using gate CD-PLAYTEST (.claude/docs/director-gates.md).

Pass: the structured report content, game pillars and core fantasy (from design/gdd/game-concept.md), the specific hypothesis being tested.

Present the creative director's assessment before saving the report. If CONCERNS or REJECT, add a ## Creative Director Assessment section to the report capturing the verdict and feedback. If APPROVE, note the approval in the report.

Phase 4: Save Report

Ask: "May I write this playtest report to production/qa/playtests/playtest-[date]-[tester].md?"

If yes, write the file, creating the directory if needed.

Phase 5: Next Steps

Verdict: COMPLETE — playtest report generated.

• Act on the highest-priority finding category first.
• After addressing design changes: re-run /design-review on the updated GDD.
• After fixing bugs: re-run /bug-triage to update priorities.