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}"
}))