!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation
Resolved above — use as-is; --review overrides review_mode for this run. No
block → defaults in .claude/docs/config-resolution.md.
Playtest Report
Phase 1: Parse Arguments
See .claude/docs/director-gates.md for the full check pattern. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.
Every AskUserQuestion call follows .claude/docs/automation-modes.md
(collaborative asks always · guided major-only · autonomous logs and proceeds;
automation_always_ask categories always prompt).
Determine the mode:
new → generate a blank playtest report template. This mode ends after
Phase 2A: a blank template has nothing to route, review or save.analyze [path] → read raw notes and fill in the template with structured findings- No argument → ask via
AskUserQuestion: [A] New blank template /
[B] Analyze notes — I'll give you the path
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]
In new mode, stop here with: Verdict: COMPLETE — blank template output; nothing saved.
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.
An observation that describes a defect — a crash, a framerate drop, a softlock,
something that plainly breaks rather than plays badly — goes in the Bugs
Encountered table, not under Gameplay Flow → Pain points, and is routed as a
bug in Phase 3. Pain points are for how the game feels to play.
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 Agent using gate CD-PLAYTEST (.claude/docs/director-gates/cd-playtest.md).
Pass: the structured report content, game pillars and core fantasy (from
design/gdd/game-concept.md), the specific hypothesis being tested. If
game-concept.md does not exist — expected at minimal, where
design/game-brief.md replaces it — the brief has no pillars: pass its
one-sentence pitch and its "Who it's for / what they feel" line instead, and say
they stand in for pillars. If neither document exists, say so in the prompt:
"No pillars available — assess against the hypothesis alone." A director gate
handed silence about pillars will invent them.
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. If NOT ASSESSED (the director lacked an input — .claude/docs/director-gates.md), add the same section naming what was missing; it is not an approval.
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.