ags-playtest-report

name	ags-playtest-report
description	Generates a structured playtest report template or analyzes existing playtest notes into a structured format. Use this to standardize playtest feedback collection and analysis.
argument-hint	[new|analyze path-to-notes]
user-invocable	true
allowed-tools	Read, Glob, Grep, Write, Task, AskUserQuestion

Language: Talk to user in language from .ags/project/user-interaction.md. Fall back to English if file missing. Files on disk always English per .ags/rules/user-interaction.md.

Phase 0: Prerequisites

Artifact	Created by	If missing
design/gdd/game-concept.md	/ags-brainstorm	STOP. "No game concept. Run /ags-brainstorm."
Playable build	dev work	WARN: report records observations only without playable session.
.ags/project/playtests/	this skill (auto-create)	Auto-create — not a STOP.

If STOP triggers, exit verdict BLOCKED.

---

Phase 1: Parse Arguments

Determine the mode:

• new → generate a blank playtest report template
• analyze [path] → read raw notes and fill in the template with structured findings

---

Phase 2A: New Template Mode

Generate this template and output it to the user:

# Playtest Report

## Session Info
- **Date**: [Date]
- **Build**: [Version/Commit]
- **Duration**: [Time played]
- **Tester**: [Name/ID]
- **Platform**: [PC/Console/Mobile]
- **Input Method**: [KB+M / Gamepad / Touch]
- **Session Type**: [First time / Returning / Targeted test]

## Test Focus
[What specific features or flows were being tested]

## First Impressions (First 5 minutes)
- **Understood the goal?** [Yes/No/Partially]
- **Understood the controls?** [Yes/No/Partially]
- **Emotional response**: [Engaged/Confused/Bored/Frustrated/Excited]
- **Notes**: [Observations]

## Gameplay Flow
### What worked well
- [Observation 1]

### Pain points
- [Issue 1 -- Severity: High/Medium/Low]

### Confusion points
- [Where the player was confused and why]

### Moments of delight
- [What surprised or pleased the player]

## Bugs Encountered
| # | Description | Severity | Reproducible |
|---|-------------|----------|-------------|

## Feature-Specific Feedback
### [Feature 1]
- **Understood purpose?** [Yes/No]
- **Found engaging?** [Yes/No]
- **Suggestions**: [Tester suggestions]

## Quantitative Data (if available)
- **Deaths**: [Count and locations]
- **Time per area**: [Breakdown]
- **Items used**: [What and when]
- **Features discovered vs missed**: [List]

## Overall Assessment
- **Would play again?** [Yes/No/Maybe]
- **Difficulty**: [Too Easy / Just Right / Too Hard]
- **Pacing**: [Too Slow / Good / Too Fast]
- **Session length preference**: [Shorter / Good / Longer]

## Top 3 Priorities from this session
1. [Most important finding]
2. [Second priority]
3. [Third priority]

---

Phase 2B: Analyze Mode

Read the raw notes at the provided path. Cross-reference with existing design documents. Fill in the template above with structured findings. Flag any playtest observations that conflict with design intent.

---

Phase 3: Action Routing

Categorize all findings into four buckets:

• Design changes needed — fun issues, player confusion, broken mechanics, observations that conflict with the GDD's intended experience
• Balance adjustments — numbers feel wrong, difficulty too spiked or too flat
• Bug reports — clear implementation defects that are reproducible
• Polish items — not blocking progress, but friction or feel issues for later

Present the categorized list, then route:

• Design changes: "Run /ags-propagate-design-change [path] on the affected design document to find downstream impacts before making changes."
• Balance adjustments: "Run /ags-balance-check [system] to verify the full balance picture before tuning values."
• Bugs: "Use /ags-bug-report to formally track these."
• Polish items: "Add to the polish backlog in .ags/project/ when the team reaches that phase."

---

Phase 3b: Creative Director Player Experience Review

After categorising findings, spawn creative-director via Task using gate CD-PLAYTEST (.ags/rules/director-gates.md).

Pass: the structured report content, game pillars and core fantasy (from design/gdd/game-concept.md), the specific hypothesis being tested.

Present the creative director's assessment before saving the report. If CONCERNS or REJECT, add a ## Creative Director Assessment section to the report capturing the verdict and feedback. If APPROVE, note the approval in the report.

---

Phase 4: Save Report

Ask: "May I write this playtest report to .ags/project/qa/playtests/playtest-[date]-[tester].md?"

If yes, write the file, creating the directory if needed.

---

Phase 5: Next Steps

Verdict: COMPLETE — playtest report generated.

• Act on the highest-priority finding category first.
• After addressing design changes: re-run /ags-design-review on the updated GDD.
• After fixing bugs: re-run /ags-bug-triage to update priorities.

---

Combined Review Loop (parallel external Codex)

Per .ags/rules/review-workflow.md. Authoring + internal review runs in parallel with external Codex inside one loop. Each iteration:

1. Resolve severity floor: iter 1-2 → keep all severities; iter 3-4 → critical/high; iter 5+ → critical only.
2. Persist current draft to .ags/project/reviews/.tmp/playtest-report-[id]-iter[N]-draft.md.
3. Spawn in one message, in parallel:
   • All internal reviewer Tasks (qa-lead + game-designer).
   • /ags-external-review custom [draft-path] --embedded-parallel --iteration [N] --min-severity [floor] — Codex unavailable returns skipped: codex-unavailable; aggregator logs skip in decisions-log and continues with internal pool only.
4. Aggregator (qa-lead) merges findings from internal + Codex, drops nitpicks + below-floor.
5. Loop exit: filtered set empty → proceed to write approval. Non-empty → surface aggregated kept findings, user revises draft, N++, repeat.

No iteration cap. No user-confirm gate before external — it runs every iteration automatically.