REVIEWING Phase — Functional Specification

1. Purpose of REVIEWING

The REVIEWING phase exists to:

• Replay each question
• Show objective outcomes (correct answer, distributions)
• Provide non-personal statistical insight
• Progress collectively, not individually

It is read-only, time-independent, and player-synchronized.

2. Scope & Non-Goals

In scope

• Cycling through questions
• Displaying:

• Original question

• Correct answer
• Aggregated statistics
• Derived “interesting facts”
• Coordinated “Next” progression
• Persisting player scores

Explicitly out of scope

• Player identity disclosure
• Individual answer attribution
• Real-time answering
• Score changes

3. Core Concepts (Mental Model)

Question Review Unit (QRU)

Each question produces one immutable review unit containing:

• Question text
• Correct answer
• Aggregated answers
• Derived statistics
• Derived facts

QRUs are processed sequentially.

4. Data Responsibilities

4.1 Player Scores (Persistent)

Must be stored before REVIEWING starts.

Each player has:

• Final score
• Optional accuracy metrics (e.g. % correct)

Rules:

• Scores are immutable during REVIEWING
• Scores may be displayed globally or privately

4.2 Question Result Dataset (Per Question)

For each question:

• Question text
• Correct answer
• All submitted answers (anonymous)
• Count of players who answered
• Distribution data (bins / groups)

This dataset is input to statistics & facts engines.

5. Statistics Engine (Deterministic)

Purpose

Transform raw answer data into neutral, aggregated metrics.

Required Outputs (minimum)

• % correct
• Answer distribution (e.g. histogram)
• Mean / median / spread (where applicable)
• Outlier detection (statistical, not personal)

Rules:

• No player identifiers
• Same input → same output
• Must complete before facts generation

6. Random Fact Engine (Controlled Randomness)

Purpose

Generate 1–X interesting, non-personal facts per question.

Inputs

• Question Result Dataset
• Statistics Engine output
• Random seed (session-scoped)

Output Characteristics

• True
• Non-identifying
• Derived from group behavior
• Explainable

Example Fact Types:

• “Most players underestimated the answer”
• “This question had the widest spread of answers”
• “Accuracy improved compared to the previous question”

Rules:

• Facts are derived, never raw
• No mention of individuals
• Upper bound X is fixed per session
• Facts are generated once, then frozen

7. REVIEWING Flow Control

State Variables

• currentQuestionIndex
• playersReadyCount
• totalPlayers
• advanceThreshold (e.g. 60%)

Next Event Aggregation

Player Action:

• Player presses Next

System Behavior:

• Record readiness (idempotent)
• Aggregate count
• Compute readiness ratio

Transition Rule:
When
playersReadyCount / totalPlayers ≥ advanceThreshold

Then:

• Advance to next question
• Reset readiness
• Broadcast transition

Safeguards:

• A player pressing Next multiple times counts once
• Late joiners do not affect threshold
• Disconnects freeze their last state

8. State Transitions

REVIEWING → REVIEWING

Occurs when:

• Threshold reached
• More questions remain

REVIEWING → FINISHED

Occurs when:

• Last question review completes
• Threshold reached

9. Invariants (Must Always Hold)

• No score changes during REVIEWING
• No personal data exposed
• All players see the same question at the same time
• Facts do not change once generated
• Advancement is collective, not individual

10. Test Strategy

10.1 Static Validation Tests

• Every question has:

• Correct answer

• Answer dataset
• Statistics engine produces output for all question types
• Fact engine produces ≤ X facts

10.2 Statistics Engine Tests

• Same dataset → same statistics
• Percentages sum correctly
• No division by zero
• Works with:

• All correct

• All incorrect
• Single-player edge case

10.3 Fact Engine Tests

• No fact references individuals
• No raw answers leaked
• Same seed → same facts
• Different seed → different selection, same truth
• Produces 0 facts if dataset too small
• Never exceeds X

10.4 REVIEWING Flow Tests

• Advance only after threshold
• Advance exactly once per question
• Multiple Next presses don’t skew count
• All players see same index

10.5 Failure & Edge Tests

• Player disconnects mid-review
• Player reconnects
• Threshold exactly met
• Threshold exceeded
• Only one player

11. Acceptance Criterion

A player can understand:

• what the correct answer was,
• how people answered in general,
• something interesting about the group,

without learning anything personal.

If yes, REVIEWING works.