gd-playtest-gdd-review

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