majiayu000 Playtest GDD Review
The 3-Phase GDD Review Process
┌─────────────────────────────────────────────────────────────────────────────┐
│ 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
# 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:
# 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
┌─────────────────────────────────────────────────────────────────────────────┐
│ 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:
## 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:
// 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
## 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:
┌─────────────────────────────────────────────────────────────────────────────┐
│ 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:
{
"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
## 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:
{
"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
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
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:
// 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}"
}))