bmad-method 6.0.0-alpha.16 → 6.0.0-alpha.18

package/src/modules/bmgd/workflows/gametest/playtest-plan/instructions.md

@@ -0,0 +1,297 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Playtest Planning
+
+**Workflow ID**: `_bmad/bmgd/gametest/playtest-plan`
+**Version**: 1.0 (BMad v6)
+
+---
+
+## Overview
+
+Create structured playtesting sessions to validate gameplay, gather user feedback, and identify issues that automated testing cannot catch. Playtesting validates "feel" and player experience.
+
+**Knowledge Base Reference**: `knowledge/playtesting.md`
+
+---
+
+## Preflight Requirements
+
+- ✅ Playable build available
+- ✅ Test objectives defined
+- ✅ Participant criteria known
+
+---
+
+## Step 1: Define Playtest Objectives
+
+### Questions to Answer
+
+1. **What are we testing?**
+   - Core gameplay loop
+   - Specific feature
+   - Difficulty curve
+   - Tutorial effectiveness
+   - Overall experience
+
+2. **What decisions will this inform?**
+   - Design changes
+   - Difficulty tuning
+   - Feature prioritization
+   - Ship/no-ship decision
+
+3. **What metrics will we collect?**
+   - Completion rates
+   - Time-on-task
+   - Failure points
+   - Player sentiment
+
+---
+
+## Step 2: Choose Playtest Type
+
+### Internal Playtest
+
+**Best for**: Early validation, bug finding, quick iterations
+
+| Aspect       | Details                   |
+| ------------ | ------------------------- |
+| Participants | Team members, other teams |
+| Duration     | 30-60 minutes             |
+| Frequency    | Weekly or per-milestone   |
+| Setup        | Minimal, informal         |
+
+### External Playtest
+
+**Best for**: Unbiased feedback, market validation
+
+| Aspect       | Details                           |
+| ------------ | --------------------------------- |
+| Participants | Target audience, external testers |
+| Duration     | 1-2 hours                         |
+| Frequency    | Monthly or milestone              |
+| Setup        | Formal, NDA if needed             |
+
+### Focused Playtest
+
+**Best for**: Specific feature validation
+
+| Aspect       | Details                      |
+| ------------ | ---------------------------- |
+| Participants | Selected for specific traits |
+| Duration     | 20-45 minutes                |
+| Frequency    | As needed                    |
+| Setup        | Specific build/scenario      |
+
+---
+
+## Step 3: Create Session Structure
+
+### Pre-Session (10-15 min)
+
+1. **Welcome & Context**
+   - Brief game description (no spoilers)
+   - Session goals (what we're testing)
+   - Comfort check (breaks, questions)
+
+2. **Consent & Setup**
+   - Recording consent (if applicable)
+   - Controller/input preferences
+   - Any accessibility needs
+
+3. **Instructions**
+   - "Play as you normally would"
+   - "Think aloud if comfortable"
+   - "There are no wrong answers"
+
+### Gameplay Session (30-90 min)
+
+1. **Observation Focus Areas**
+   - Where do players get stuck?
+   - What do they try first?
+   - What surprises them?
+   - Where do they express frustration/joy?
+
+2. **Note-Taking Template**
+
+   ```
+   [TIME] [LOCATION] [OBSERVATION] [PLAYER REACTION]
+   0:05   Tutorial    Skipped help text    Seemed impatient
+   0:12   Combat      Died to first enemy  Frustrated, retried
+   ```
+
+3. **Intervention Rules**
+   - Let players struggle (within reason)
+   - Note when you want to help
+   - Only intervene for:
+     - Critical bugs
+     - Genuine distress
+     - Session time running out
+
+### Post-Session (10-20 min)
+
+1. **Immediate Reactions**
+   - "What was your overall impression?"
+   - "What stood out most?"
+   - "Would you play again?"
+
+2. **Specific Questions**
+   - Feature-specific feedback
+   - Difficulty perception
+   - Clarity of objectives
+
+3. **Open Feedback**
+   - "Anything else?"
+   - "Questions for us?"
+
+---
+
+## Step 4: Create Observation Guide
+
+### What to Watch For
+
+| Category    | Signals                               | Record             |
+| ----------- | ------------------------------------- | ------------------ |
+| Confusion   | Pausing, wandering, repeating actions | Location, duration |
+| Frustration | Sighing, repeated failures, quitting  | Cause, frequency   |
+| Engagement  | Leaning in, exclaiming, continuing    | Features that work |
+| Boredom     | Checking phone, disengaging           | Drop-off points    |
+
+### Quantitative Metrics
+
+- Time to complete tutorial
+- Deaths per section
+- Items/features discovered
+- Session duration
+- Completion rate
+
+---
+
+## Step 5: Generate Playtest Plan Document
+
+### Document Structure
+
+```markdown
+# Playtest Plan: {Build/Feature Name}
+
+## Overview
+
+- Build version: {version}
+- Session date(s): {dates}
+- Objective: {primary goal}
+
+## Participant Criteria
+
+- Target: {player type}
+- Experience: {gaming background}
+- Count: {number}
+
+## Session Structure
+
+### Pre-Session (15 min)
+
+- Welcome and consent
+- Setup and preferences
+- Brief instructions
+
+### Gameplay (60 min)
+
+- Free play / guided tasks
+- Observation focus: {areas}
+- Intervention threshold: {criteria}
+
+### Post-Session (15 min)
+
+- Immediate reactions
+- Structured questions
+- Open feedback
+
+## Observation Guide
+
+{observation_template}
+
+## Data Collection
+
+- Recording: {yes/no}
+- Notes template: {attached}
+- Metrics: {list}
+
+## Team Roles
+
+- Facilitator: {name}
+- Note-taker: {name}
+- Technical support: {name}
+
+## Post-Playtest Analysis
+
+- Session debrief: {date}
+- Report due: {date}
+- Action items review: {date}
+```
+
+---
+
+## Step 6: Post-Playtest Analysis
+
+### Synthesize Findings
+
+1. **Pattern Identification**
+   - What issues appeared multiple times?
+   - What worked consistently well?
+
+2. **Severity Assessment**
+   - Critical: Blocks progression
+   - Major: Significantly impacts experience
+   - Minor: Noticeable but manageable
+
+3. **Recommendations**
+   - Immediate fixes
+   - Design considerations
+   - Further investigation needed
+
+### Report Template
+
+```markdown
+## Playtest Report: {Session}
+
+### Summary
+
+- Participants: {count}
+- Completion rate: {%}
+- Overall sentiment: {positive/mixed/negative}
+
+### Key Findings
+
+1. {Finding with evidence}
+2. {Finding with evidence}
+
+### Recommendations
+
+| Issue   | Severity | Recommendation | Priority |
+| ------- | -------- | -------------- | -------- |
+| {issue} | {sev}    | {rec}          | {P0-P3}  |
+
+### Quotes
+
+> "{Notable player quote}" - Participant {N}
+
+### Next Steps
+
+1. {action item}
+2. {action item}
+```
+
+---
+
+## Deliverables
+
+1. **Playtest Plan Document** - Session structure and logistics
+2. **Observation Guide** - What to watch for
+3. **Note-Taking Template** - Standardized recording
+4. **Report Template** - Post-session analysis format
+
+---
+
+## Validation
+
+Refer to `checklist.md` for validation criteria.

package/src/modules/bmgd/workflows/gametest/playtest-plan/playtest-template.md

@@ -0,0 +1,208 @@
+# Playtest Plan: {BUILD_NAME}
+
+**Version**: {BUILD_VERSION}
+**Created**: {DATE}
+**Session Date(s)**: {PLAYTEST_DATES}
+
+---
+
+## Overview
+
+### Objective
+
+{What are we trying to learn from this playtest?}
+
+### Build Information
+
+- **Version**: {version}
+- **Platform**: {PC/Console/Mobile}
+- **Content**: {What's included in this build}
+- **Known Issues**: {List any known bugs to ignore}
+
+### Success Criteria
+
+{How will we know the playtest was successful?}
+
+---
+
+## Participants
+
+### Target Profile
+
+- **Player Type**: {casual/core/hardcore}
+- **Genre Experience**: {familiar/unfamiliar with genre}
+- **Age Range**: {if relevant}
+- **Other Criteria**: {specific requirements}
+
+### Recruitment
+
+- **Count**: {number of participants}
+- **Source**: {internal/external/panel}
+- **Compensation**: {if applicable}
+
+---
+
+## Session Structure
+
+### Pre-Session (15 minutes)
+
+1. **Welcome (5 min)**
+   - Introduce yourself and the team
+   - Explain what they'll be doing
+   - Emphasize: "We're testing the game, not you"
+
+2. **Consent & Setup (5 min)**
+   - Recording consent: {yes/no}
+   - NDA: {yes/no}
+   - Collect demographic info: {yes/no}
+   - Hardware preferences
+
+3. **Instructions (5 min)**
+   - "Play as you normally would"
+   - "Think out loud if you're comfortable"
+   - "Ask questions anytime"
+   - "You can stop at any time"
+
+### Gameplay Session ({DURATION} minutes)
+
+#### Free Play vs Guided Tasks
+
+- [ ] Free play - Let player explore naturally
+- [ ] Guided tasks - Specific scenarios to complete
+
+#### Focus Areas
+
+1. {Area 1 - e.g., Tutorial effectiveness}
+2. {Area 2 - e.g., Combat feel}
+3. {Area 3 - e.g., Navigation clarity}
+
+#### Intervention Threshold
+
+Only intervene when:
+
+- [ ] Critical bug prevents progress
+- [ ] Player is genuinely distressed
+- [ ] Session time is running out
+- [ ] Player explicitly asks for help
+
+### Post-Session ({POST_DURATION} minutes)
+
+#### Immediate Reactions
+
+1. "What was your overall impression of the game?"
+2. "What moment stood out the most?"
+3. "Would you play this again? Why or why not?"
+
+#### Feature-Specific Questions
+
+1. {Question about focus area 1}
+2. {Question about focus area 2}
+3. {Question about focus area 3}
+
+#### Open Feedback
+
+1. "Is there anything you wish the game had?"
+2. "Anything else you'd like to share?"
+3. "Questions for us?"
+
+---
+
+## Observation Guide
+
+### What to Watch For
+
+| Signal          | Examples                               | Action                    |
+| --------------- | -------------------------------------- | ------------------------- |
+| **Confusion**   | Pausing, circling, re-reading          | Note location, duration   |
+| **Frustration** | Sighing, repeated attempts, quitting   | Note cause, frequency     |
+| **Engagement**  | Leaning in, exclaiming, "one more try" | Note feature              |
+| **Boredom**     | Checking phone, rushing, disengaging   | Note when drop-off begins |
+| **Discovery**   | "Oh!", trying things                   | Note what triggered it    |
+
+### Metrics to Collect
+
+- [ ] Time to complete tutorial
+- [ ] Number of deaths/failures per section
+- [ ] Features/items discovered
+- [ ] Total session duration
+- [ ] Completion rate
+
+---
+
+## Note-Taking Template
+
+```
+Participant: ___  Date: ___  Observer: ___
+
+TIME | LOCATION | OBSERVATION | REACTION | NOTES
+-----|----------|-------------|----------|------
+     |          |             |          |
+     |          |             |          |
+     |          |             |          |
+
+Key Moments:
+1.
+2.
+3.
+
+Overall Impression:
+
+```
+
+---
+
+## Team Roles
+
+| Role             | Responsibilities                  | Assigned To |
+| ---------------- | --------------------------------- | ----------- |
+| **Facilitator**  | Welcome, instructions, interview  | {name}      |
+| **Note-taker**   | Observations, timestamps          | {name}      |
+| **Tech Support** | Build, recording, troubleshooting | {name}      |
+
+---
+
+## Logistics
+
+### Equipment
+
+- [ ] Game build installed and tested
+- [ ] Controllers/input devices
+- [ ] Recording equipment (if applicable)
+- [ ] Consent forms
+- [ ] Observation templates (printed)
+- [ ] Compensation (if applicable)
+
+### Environment
+
+- [ ] Quiet, private space
+- [ ] Comfortable seating
+- [ ] Water/snacks available
+- [ ] Clock/timer visible
+
+---
+
+## Post-Playtest Process
+
+### Same Day
+
+- [ ] Quick team debrief (15 min)
+- [ ] Consolidate raw notes
+- [ ] Flag critical issues
+
+### Within 48 Hours
+
+- [ ] Synthesize findings
+- [ ] Identify patterns
+- [ ] Draft playtest report
+
+### Report Delivery
+
+- **Due Date**: {date}
+- **Distribution**: {team/stakeholders}
+- **Format**: {document/presentation}
+
+---
+
+## Notes
+
+{Any additional notes, special considerations, or reminders}

package/src/modules/bmgd/workflows/gametest/playtest-plan/workflow.yaml

@@ -0,0 +1,59 @@
+# Game QA workflow: playtest-plan
+name: gametest-playtest-plan
+description: "Create structured playtesting sessions for gameplay validation and user feedback"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/_bmad/bmgd/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/_bmad/bmgd/workflows/gametest/playtest-plan"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+template: "{installed_path}/playtest-template.md"
+
+# Variables and inputs
+variables:
+  playtest_type: "internal" # internal, external, focused
+  session_duration: 60 # minutes
+  participant_count: 5
+
+# Smart input file references - for understanding game mechanics to test
+input_file_patterns:
+  gdd:
+    description: "Game Design Document for mechanics to validate"
+    whole: "{output_folder}/*gdd*.md"
+    sharded: "{output_folder}/*gdd*/*.md"
+    load_strategy: "FULL_LOAD"
+  game_brief:
+    description: "Game Brief for understanding core pillars"
+    whole: "{output_folder}/*brief*.md"
+    load_strategy: "FULL_LOAD"
+
+# Output configuration
+default_output_file: "{output_folder}/playtest-plan.md"
+
+# Required tools
+required_tools:
+  - read_file
+  - write_file
+  - list_files
+
+tags:
+  - qa
+  - playtesting
+  - user-research
+  - design-validation
+  - feedback
+
+execution_hints:
+  interactive: true
+  autonomous: false
+  iterative: true
+
+web_bundle: false

package/src/modules/bmgd/workflows/gametest/test-design/checklist.md

@@ -0,0 +1,98 @@
+# Game Test Design - Validation Checklist
+
+---
+
+## Prerequisites
+
+- [ ] Game design documentation reviewed
+- [ ] Core mechanics identified
+- [ ] Target platforms known
+- [ ] Risk areas assessed
+
+---
+
+## Context Gathering
+
+- [ ] GDD or feature specs located
+- [ ] Core gameplay loop understood
+- [ ] Progression systems identified
+- [ ] Multiplayer requirements known (if applicable)
+- [ ] Platform certification needs identified
+
+---
+
+## Test Categories
+
+### Gameplay Tests
+
+- [ ] Core loop scenarios created
+- [ ] Combat/interaction tests defined
+- [ ] Movement/physics tests defined
+- [ ] UI/UX tests defined
+
+### Progression Tests
+
+- [ ] Save/load scenarios created
+- [ ] Unlock system tests defined
+- [ ] Economy tests defined
+- [ ] Achievement tests defined
+
+### Multiplayer Tests (if applicable)
+
+- [ ] Connectivity scenarios created
+- [ ] Sync validation tests defined
+- [ ] Latency tests defined
+- [ ] Matchmaking tests defined
+
+### Platform Tests
+
+- [ ] Certification requirements covered
+- [ ] Input handling tests defined
+- [ ] Performance criteria established
+- [ ] Accessibility tests defined
+
+---
+
+## Scenario Quality
+
+- [ ] All scenarios use GIVEN/WHEN/THEN format
+- [ ] Scenarios have clear expected outcomes
+- [ ] Priorities assigned (P0-P3)
+- [ ] Categories assigned
+- [ ] No duplicate scenarios
+- [ ] Edge cases considered
+
+---
+
+## Prioritization
+
+- [ ] P0 scenarios cover ship blockers
+- [ ] P1 scenarios cover major features
+- [ ] Priority distribution is reasonable
+- [ ] Risk-based ordering applied
+
+---
+
+## Documentation
+
+- [ ] Test design document created
+- [ ] Overview section complete
+- [ ] Risk assessment included
+- [ ] Coverage matrix generated
+- [ ] Automation recommendations provided
+- [ ] Next steps defined
+
+---
+
+## Completion Criteria
+
+- [ ] All critical systems have test coverage
+- [ ] Scenarios are actionable and testable
+- [ ] Document is ready for team review
+- [ ] Automation candidates identified
+
+---
+
+**Completed by:** {name}
+**Date:** {date}
+**Scenario Count:** {count}