--- name: gd-playtest-gdd-review description: GDD review and research during playtest phase. Use during playtest phase BEFORE sending playtest_session_report to PM, after completing gameplay testing, after reviewing retrospective pain points, or before finalizing the playtest report. --- # 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 ```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 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 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: ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 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 ``` 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: ```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}" })) ``` --- Source attribution: feliperyba Original project: https://github.com/feliperyba/ralph-orchestra/blob/9338a5a194fac4e20e174decc6ce1b7400744866/.claude/skills/gd-playtest-gdd-review/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 feliperyba Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: feliperyba Original project: https://github.com/feliperyba/ralph-orchestra/blob/9338a5a194fac4e20e174decc6ce1b7400744866/.claude/skills/gd-playtest-gdd-review/SKILL.md Attribution basis: Recovered original package and original project license at a pinned revision Fields of work: Design, Development & Engineering, Product Management, Project & Program Management Roles: Game Developer, Product Manager, Project Manager, QA / Test Engineer, UX Designer Specialties: Specialty not specified Tools: Retrospective Tool, Playwright Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 5be9e02440ca32bddad26efeb844914265e03bdb93b274f7d141b023766c0013 Metadata reviewed: 2026-10-27 This metadata supersedes earlier Mega AI Hub catalog attribution. Original instruction and supporting files are preserved.