Playtest GDD Review
The 3-Phase GDD Review Process
code
┌─────────────────────────────────────────────────────────────────────────────┐ │ PLAYTEST GDD REVIEW WORKFLOW │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Phase 1: RETROSPECTIVE ANALYSIS │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 1. Read retrospective.txt for pain points │ │ │ │ 2. Identify worker struggles: unclear specs, missing references │ │ │ │ 3. Note repeated questions about GDD content │ │ │ │ 4. Catalog implementation deviations from design │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ Phase 2: GAME STATE REVIEW │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 1. Review current implementation via Playwright MCP │ │ │ │ 2. Compare actual gameplay vs GDD specifications │ │ │ │ 3. Check docs/design/gdd/ for outdated sections │ │ │ │ 4. Verify acceptance criteria alignment │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ Phase 3: GAP ANALYSIS & UPDATE PROPOSAL │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 1. Identify GDD sections needing updates │ │ │ │ 2. Catalog missing specifications │ │ │ │ 3. Identify skills workers need but don't have │ │ │ │ 4. Propose task priority adjustments │ │ │ │ 5. Update GDD files if changes are clear │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ Include in playtest_report │ │ │ └─────────────────────────────────────────────────────────────────────────────┘
Phase 1: Retrospective Analysis
Step 1: Read Retrospective
bash
# Read the most recent retrospective using Read tool
Read(".claude/session/retrospective.txt")
# Extract pain points from each worker section
# Look for sections: Developer Perspective, Tech Artist Perspective, QA Perspective
Step 2: Identify GDD-Related Pain Points
Look for patterns indicating GDD issues:
| Pain Point Pattern | GDD Issue Type | Action |
|---|---|---|
| "Unclear what X means" | Ambiguous specification | Clarify in GDD |
| "Not specified how Y works" | Missing specification | Add to GDD |
| "Had to guess Z" | Incomplete design | Complete design |
| "Reference images unclear" | Visual reference gap | Add/update references |
| "Conflicting specs in X and Y" | Contradiction | Resolve conflict |
| "No examples for pattern" | Missing examples | Add code/visual examples |
Step 3: Catalog Questions from Workers
Use native Read/Write tools to check for messages:
bash
# Use Glob to find messages in your inbox
Glob(".claude/session/messages/gamedesigner/msg-*.json")
# Read each message file using Read tool
# Look for type "question" or "design_question"
# Track patterns of what workers are asking about
# Log question topics for GDD update analysis
Question patterns to catalog:
| Pattern | What it means | Action |
|---|---|---|
| design_question | Asking about design intent | Clarify in GDD |
| reference_request | Needs visual reference | Add/update references |
| clarification | Unclear specification | Add details to GDD |
Phase 2: Game State Review
Step 1: Compare Implementation vs GDD
code
┌─────────────────────────────────────────────────────────────────────────────┐ │ IMPLEMENTATION vs GDD CHECKLIST │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ GDD Module │ Implementation │ Gap? │ │ ───────────────────────────────┼────────────────┼─────────────────────────│ │ 2_paint_friction_system.md │ [Review src/] │ Values differ? │ │ 3_movement_system.md │ [Review src/] │ Controls different? │ │ 4_territory_control.md │ [Review src/] │ Grid size mismatch? │ │ 5_weapon_system.md │ [Review src/] │ Weapon behavior off? │ │ 8_ui_hud_system.md │ [Review src/] │ HUD elements missing? │ │ 13_multiplayer.md │ [Review src/] │ Network pattern wrong? │ │ │ └─────────────────────────────────────────────────────────────────────────────┘
Step 2: Check GDD Currency
For each GDD module, verify:
markdown
## GDD Currency Checklist ### [Module Name].md - [ ] Version number updated - [ ] Last updated date current - [ ] Acceptance criteria match PRD - [ ] Technical specs accurate - [ ] Reference images still relevant - [ ] No TODO comments unresolved - [ ] No conflicting specifications
Step 3: Vision MCP Analysis
Use Vision MCP to compare gameplay with GDD visual specifications:
javascript
// Analyze gameplay screenshot against GDD visual specs
const gddVisualCheck = await visionAnalyze(screenshot, {
prompt: `Compare this gameplay screenshot against GDD visual requirements:
- Character: [GDD spec]
- UI: [GDD spec]
- Environment: [GDD spec]
Report any deviations with severity (low/medium/high).`,
});
Phase 3: Gap Analysis & Update Proposal
Step 1: Identify GDD Updates Needed
markdown
## GDD Update Proposals | Task ID | GDD Module | Issue | Proposed Update | Priority | | ------------ | -------------------------- | --------------------------- | ------------------------- | -------- | | P1-001 | 2_paint_friction_system.md | Friction values unclear | Add specific values table | HIGH | | P1-002 | 4_territory_control.md | Grid cell size ambiguous | Specify 2mx2m explicitly | HIGH | | feat-tps-001 | TPS_CAMERA_SPEC.md | No shoulder offset examples | Add code examples | CRITICAL |
Step 2: Identify Missing Skills
Analyze worker struggles to identify skill gaps:
code
┌─────────────────────────────────────────────────────────────────────────────┐ │ SKILL GAP ANALYSIS │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Worker Struggle │ Missing Skill │ │ ─────────────────────────────────────┼───────────────────────────────────│ │ "Don't know X pattern" │ dev-patterns-[X] │ │ "Unsure how to integrate Y" │ dev-integration-[Y] │ │ "Visual reference unclear for Z" │ gd-visual-reference-[Z] │ │ "Performance issues with W" │ dev-performance-[W] │ │ "Shader doesn't match spec V" │ ta-shader-[V]-examples │ │ │ └─────────────────────────────────────────────────────────────────────────────┘
Step 3: Propose Task Priority Adjustments
Based on playtest findings, recommend priority changes:
json
{
"priorityRecommendations": [
{
"taskId": "P1-00X",
"currentTier": "TIER_3",
"recommendedTier": "TIER_1",
"reason": "Blocks multiple user-facing features, discovered during playtest"
},
{
"taskId": "iter6-0XX",
"currentTier": "TIER_2",
"recommendedTier": "TIER_4",
"reason": "Lower impact than expected, can defer"
}
]
}
GDD Update Process
When to Update GDD Immediately
Update GDD files directly when:
- •Specification is clearly wrong (e.g., typo in values)
- •Acceptance criteria are ambiguous
- •Missing examples that would prevent work
- •Visual references are outdated
When to Propose Updates
Propose updates (include in report) when:
- •Design changes need team discussion
- •New features affect multiple GDD sections
- •Priority changes affect planning
- •Scope changes need PM approval
GDD Update Template
markdown
## GDD Update: [Module Name] **Date:** YYYY-MM-DD **Updated By:** Game Designer **Trigger:** Playtest [taskId] - Retrospective analysis ### Changes Made | Section | Before | After | Reason | | --------- | ------------- | ------------- | ------------- | | [Section] | [Old content] | [New content] | [Why changed] | ### Impact on Tasks | Task ID | Impact | Action Required | | -------- | ------------- | ----------------------- | | [taskId] | [Description] | [What worker should do] | ### Version Update - Previous: X.Y.Z - New: X.Y.Z+1
Playtest Report Additions
Include these sections in playtest_session_report:
json
{
"taskId": "{taskId}",
"playtestResult": {
"overall": "PASS|FAIL|PARTIAL",
"criteriaTested": [...],
"issuesFound": [...]
},
"gddReview": {
"modulesReviewed": ["2_paint_friction_system.md", "4_territory_control.md"],
"updatesNeeded": [
{
"task": "P1-001",
"gddModule": "2_paint_friction_system.md",
"issue": "Friction values ambiguous",
"proposedChange": "Add explicit values table",
"priority": "HIGH"
}
],
"gddUpdatesMade": [
{
"file": "docs/design/gdd/4_territory_control.md",
"change": "Clarified grid cell size as 2mx2m",
"version": "1.2.0"
}
]
},
"skillGaps": [
{
"agent": "developer",
"missingSkill": "dev-patterns-friction-transition",
"description": "Workers struggled with smooth surface transitions",
"proposedSkill": "Create skill for 100ms friction blend patterns"
}
],
"priorityRecommendations": [
{
"taskId": "P1-008",
"currentTier": "TIER_3",
"recommendedTier": "TIER_2",
"reason": "Critical for UX, discovered friction testing difficult without it"
}
]
}
Sub-Agent Coordination
Use skill-researcher for Skill Proposals
code
If skill gaps identified: 1. Document gap clearly 2. Use Task with skill-researcher sub-agent 3. Research existing similar skills 4. Propose new skill structure 5. Include in playtest report
Update GDD Files
code
If clear GDD updates needed: 1. Read the GDD module 2. Edit with clarifications 3. Update version number 4. Document change in decision_log.md 5. List updated files in playtest report
Quality Gates
Before sending playtest report:
- • Retrospective pain points reviewed
- • Worker questions analyzed
- • Game state compared to GDD
- • GDD modules checked for currency
- • Skill gaps documented
- • GDD updates made (if clear) or proposed
- • Priority recommendations justified
- • All findings included in playtest report
Messages You Send
After GDD review, use Write tool to send the playtest report:
javascript
// Use Write tool to send message to PM's inbox:
Write(".claude/session/messages/pm/msg-playtest-{timestamp}.json", JSON.stringify({
"id": "msg-playtest-report-{timestamp}",
"from": "gamedesigner",
"to": "pm",
"type": "playtest_session_report",
"payload": {
"taskId": "{taskId}",
"playtestResult": {
"overall": "PASS|FAIL|PARTIAL",
"criteriaTested": [...],
"issuesFound": [...]
},
"gddReview": {
"modulesReviewed": ["2_paint_friction_system.md", "4_territory_control.md"],
"updatesNeeded": [...],
"gddUpdatesMade": [...]
},
"skillGaps": [...],
"priorityRecommendations": [...]
},
"timestamp": "{ISO-8601-UTC}"
}))