Playtest report schema

Contract

Enforces one fixed structure for every game playtest report: nine top-level ## sections in a fixed order, exact field labels, and a closed vocabulary for the graded fields. Apply whenever asked to produce a playtest report, a blank template, or to turn raw playtest notes into a structured writeup.

Rules

R1 — The nine sections, in this exact order

Every report has these nine ## sections and no others, in order. Never rename, merge, drop, reorder, or insert extra top-level sections.

1. ## Session Info
2. ## Test Focus
3. ## First Impressions (First 5 minutes)
4. ## Gameplay Flow
5. ## Bugs Encountered
6. ## Feature-Specific Feedback
7. ## Quantitative Data (if available)
8. ## Overall Assessment
9. ## Top 3 Priorities from this session

Keep the parentheticals verbatim: (First 5 minutes) on section 3 and (if available) on section 7.

R2 — Session Info fields

A bullet list with EXACTLY these seven bold labels, in this order: Date, Build, Duration, Tester, Platform, Input Method, Session Type. The label for how the player controlled the game is always Input Method — never "Controller", never "Control Scheme", never "Input". The person label is Tester — never "Tester Name", never "Player".

R3 — Test Focus

One line stating what was being tested (a feature, a flow, or "general / first pass"). Comes second, directly after Session Info.

R4 — First Impressions (First 5 minutes) fields

Bullets with these labels: Understood the goal?, Understood the controls?, Emotional response, Notes. Keep the (First 5 minutes) qualifier in the heading. The two "Understood…?" answers are one of Yes / No / Partially.

R5 — Gameplay Flow subsections

Exactly four ### subsections, in this order: What worked well, Pain points, Confusion points, Moments of delight. Each Pain point bullet ends with the suffix -- Severity: High/Medium/Low. Do not rename "Moments of delight" to "Highlights"/"Positives", and do not collapse the four into "Pros/Cons".

R6 — Bugs Encountered table

A Markdown table with EXACTLY these four columns, in this order: # | Description | Severity | Reproducible. The Reproducible cell is Yes or No (never "Always/Sometimes/Never", never a percentage). Do not add Status, Priority, Steps, or Owner columns.

R7 — Feature-Specific Feedback

One block per feature, each with bullets Understood purpose?, Found engaging?, Suggestions.

R8 — Quantitative Data (if available)

Bullets with labels Deaths, Time per area, Items used, Features discovered vs missed. Keep the section even when empty (write "n/a" per line); keep the (if available) qualifier.

R9 — Overall Assessment

Bullets: 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). Each answer is one of its listed tokens, verbatim.

R10 — Top 3 Priorities from this session

A numbered list of EXACTLY three items, most important first. Not two, not five, not "Top Priorities" — always exactly three, and always the final section.

R11 — Closed vocabularies

Use these tokens exactly; no synonyms anywhere in the report:

• Severity: High / Medium / Low (never Critical/Major/Minor, never P0/P1, never "minor"/"blocker").
• Emotional response: Engaged / Confused / Bored / Frustrated / Excited.
• Difficulty: Too Easy / Just Right / Too Hard.
• Pacing: Too Slow / Good / Too Fast.
• Session length preference: Shorter / Good / Longer.
• Reproducible / Would play again Yes/No answers as listed above.

R12 — Action routing buckets

When sorting findings for follow-up, use EXACTLY these four buckets, no others: Design changes needed (fun issues, player confusion, broken mechanics), Balance adjustments (numbers feel wrong, difficulty spiked or flat), Bug reports (reproducible implementation defects, crashes), Polish items (non-blocking friction/feel for later). Not "Must-fix / Nice-to-have", not "P0/P1/P2".

Worked examples

R2 — Input Method label (BEFORE → AFTER)

BEFORE (base default invents its own label):

## Session Info
- Date: 2026-06-26
- Controller: Gamepad
- Player Name: Priya

AFTER (exact labels + order):

## Session Info
- **Date**: 2026-06-26
- **Build**: v0.4.1
- **Duration**: 40 min
- **Tester**: Priya
- **Platform**: Steam Deck
- **Input Method**: Gamepad
- **Session Type**: First time

R5 — Gameplay Flow + Severity suffix (BEFORE → AFTER)

BEFORE (base merges into Pros/Cons, no severity):

## Gameplay Flow
### Pros
- Combat feels great
### Cons
- Double jump is unclear

AFTER (four fixed subsections, severity suffix on pain points):

## Gameplay Flow
### What worked well
- Combat feels responsive and weighty
### Pain points
- Double-jump timing window is too tight -- Severity: Medium
### Confusion points
- Players didn't realize the crafting menu existed
### Moments of delight
- The boss-fight music drew an audible reaction

R6 — Bug table columns (BEFORE → AFTER)

BEFORE (base picks its own columns + reproducibility words):

## Bugs
| Bug | Steps | Priority | Status |
|-----|-------|----------|--------|
| Crash on pause | Pause in level 3 | P0 | Open |

AFTER (exact four columns, Yes/No, High/Medium/Low):

## Bugs Encountered
| # | Description | Severity | Reproducible |
|---|-------------|----------|--------------|
| 1 | Game crashes when pausing in level 3 | High | Yes |

R9/R11 — Difficulty vocabulary (BEFORE → AFTER)

BEFORE (free-form): - Difficulty: felt a bit on the easy side AFTER (closed token): - **Difficulty**: Too Easy

R4 — Emotional response vocabulary (BEFORE → AFTER)

BEFORE: - Emotional response: kind of lost at first, then into it AFTER: - **Emotional response**: Confused

R1/R3 — Section order (BEFORE → AFTER)

BEFORE (base front-loads bugs, drops qualifiers):

## Bugs
## Overview
## First Impressions

AFTER: the nine sections in the R1 order, with Session Info first, Test Focus second, and Top 3 Priorities from this session last.

R10 — Exactly three priorities (BEFORE → AFTER)

BEFORE (base lists five "key takeaways"):

## Key Takeaways
1. … 2. … 3. … 4. … 5. …

AFTER:

## Top 3 Priorities from this session
1. Fix the level-3 pause crash
2. Clarify the double-jump tutorial
3. Add a difficulty bump to the early game

R12 — Action buckets (BEFORE → AFTER)

BEFORE: Must-fix: / Nice-to-have: AFTER: Design changes needed: / Balance adjustments: / Bug reports: / Polish items:

Edge cases & exceptions

• Blank template requested. Still emit all nine sections in order with all

field labels; fill values with placeholders like [Date], [Yes/No/Partially], and leave the bug table header row with an empty body.

• Raw notes missing a section's data. Keep the section and its labels; write

"n/a" or "not observed" rather than deleting the section.

• A bug whose reproducibility is unknown. Reproducible is still Yes or No —

pick "No" when not confirmed reproducible; do not invent "Unknown".

• Notes say "minor UI bug". Map the loose word to the closed token: "minor" →

Low, "major"/"blocker"/"crash" → High, in-between → Medium.

• A confusion item that is also a bug. Confusion goes under Gameplay Flow →

Confusion points; the reproducible defect ALSO gets a row in Bugs Encountered. They are not mutually exclusive.

• Multiple features tested. Repeat the Feature-Specific Feedback block (the

three bullets) once per feature under the single section heading.

• Targeted test of one system. Session Type reflects the targeted test and

Test Focus names the system; the schema is otherwise unchanged.

Do / Don't

• Always label control input Input Method; never "Controller" or "Control Scheme".
• Always keep (First 5 minutes) and (if available) in the headings; never strip them.
• Always use High / Medium / Low for severity; never Critical/Major/Minor or P0/P1.
• Always end every Pain point with -- Severity: …; never leave a pain point unrated.
• Always emit exactly the four Gameplay Flow subsections; never collapse to Pros/Cons.
• Always end with exactly three priorities; never two, five, or "Top Priorities".
• Always make the bug table # | Description | Severity | Reproducible; never add Status/Priority/Steps.
• Always pick a closed token for Difficulty/Pacing/Session length; never free-form prose.

Common mistakes

• Renaming Input Method to "Controller" or merging Platform + Input Method.
• Dropping the (First 5 minutes) / (if available) qualifiers.
• Using P0/P1 or Critical/Major/Minor for severity instead of High/Medium/Low.
• Writing reproducibility as "Always/Sometimes" instead of Yes/No.
• Collapsing the four Gameplay Flow subsections into Pros/Cons or Strengths/Weaknesses.
• Adding Status/Priority/Owner columns to the Bugs Encountered table.
• Producing 4–5 priorities, or titling it "Top Priorities" instead of "Top 3 Priorities from this session".
• Free-form Difficulty/Pacing ("a little slow") instead of the closed token ("Too Slow").
• Routing findings into ad-hoc buckets ("Must-fix / Nice-to-have") instead of the four canonical buckets.

Quick checklist

• ] Nine sections, exact order, qualifiers intact.
• ] Session Info: Date, Build, Duration, Tester, Platform, Input Method, Session Type.
• ] First Impressions has the four labels; Yes/No/Partially answers.
• ] Gameplay Flow: four subsections; each pain point ends -- Severity: High/Medium/Low.
• ] Bug table: # | Description | Severity | Reproducible; Reproducible = Yes/No.
• ] Closed vocab everywhere: Severity, Emotional response, Difficulty, Pacing, Session length.
• ] Exactly three items in "Top 3 Priorities from this session".
• ] Findings routed into the four canonical buckets only.