Agent skill

gd-playtest-gdd-review

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/gd-playtest-gdd-review

SKILL.md

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

Didn't find tool you were looking for?

Be as detailed as possible for better results