ADR-054: Scenario clarity — stakes, jargon translation, and decision-prompt concreteness¶

Status: Accepted Date: 2026-05-12 Context: A generated boardroom multiplayer scenario ("The Count") produced a comprehension failure: players reported not understanding what the objective was, what was wrong, or what they were trying to accomplish. The scenario described an academic enrollment decline and a Budget Committee meeting, but: (1) the specific worst-case outcome was never named in concrete terms ("becomes someone else's narrative" is not a consequence); (2) specialist vocabulary ("cross-listed courses," "Budget Committee," "provost's office") was used without translation; (3) the scenario body drifted into third-person narration ("Dr. Voss has 48 hours...") despite the voice contract requiring 2nd-person throughout; (4) the decision prompt ended with a meta-question ("The question isn't whether to respond. It's how fast, and with whose voice.") rather than naming what's concretely at stake.

These failures trace to three under-specified principles: Principle #5 ("Clear stakes") was one sentence with no test; Principle #10 ("Domain accessibility") had no operationalizable check; and Principle #1's 2nd-person requirement applied to the first sentence but not the description body. The Voice & Format decision-prompt rule gave examples of good prompts but didn't explicitly ban the meta-question failure mode.

At a glance

What it decides: Generated scenarios must clear a higher comprehension bar — the specific bad outcome is named in concrete human terms, institutional jargon is translated, the player is "you" throughout the body, and the decision prompt states what's concretely at stake rather than posing a poetic meta-question.

Expands three existing principles, adds none — #5 (clear stakes) becomes three tests, #10 (accessibility) gets a "could a smart outsider understand this?" jargon test, #1 extends 2nd-person to the whole body.
Bans the meta-question decision prompt — "the question is how you respond" out; "the Budget Committee meets Thursday 9AM, move first or someone frames this as a failing program" in.
Rejected a new validator and a one-off DB fix — the prompt-side test is more robust than enumerating jargon, and fixing the class beats fixing the instance.
Watch for: over-explained scenarios that read like tutorials against the word limit; the narrative-bleed detector still only checks the first sentence for 3rd-person drift.

Decision¶

Expand three existing principles and tighten the decision-prompt rule. No new principles added — the gaps are in specificity, not coverage.

Principle #1 — add explicit "2nd person throughout the description body, not just the opening sentence." Player is always "you," never "Dr. Voss" or "the CEO" in the narration.

Principle #5 — expand from one line to three specific requirements: 1. Name the specific bad outcome in concrete terms (faculty lines cut, contract lost, staff laid off — not "program at risk") 2. Translate every institutional consequence into human terms ("formal review" → "external committee decides within 90 days whether to close the program") 3. State what a good outcome looks like — players need to know what they're fighting for, not just what they're afraid of

Principle #10 — add an operationalizable jargon test ("could a smart person with no background in this field understand what this means and why it matters?") with the cross-listed-courses scenario as the named anti-pattern, and a three-question comprehension test to run before finalizing the description: does the player know (1) what specifically went wrong, (2) what the worst-case outcome is in plain human terms, (3) what a good outcome looks like?

Decision-prompt rule — ban the meta-question form explicitly. The prompt must name what's concretely at stake if no choice is made, not just the frame around the decision. Add examples of the failure mode alongside examples of the passing form.

Rationale¶

The comprehension failure is upstream of scenario quality. Worldview-split options (ADR-053), constraint discipline (ADR-037), and case-study voice (ADR-034) all assume the player understood the scenario — if they didn't, none of the other quality work lands. Principle #5 was structurally too weak: "what's at risk?" is a question the author is supposed to answer, but there was no test for whether the answer was concrete enough. Principle #10 existed but was aspirational ("ensure accessibility") without giving the model a procedure to follow.

The jargon test matters particularly for institutional scenarios (academic, government, legal, medical) where specialist vocabulary carries obvious meaning to insiders and zero meaning to anyone else. "Cross-listed courses create a methodology question" fails a high-school student and probably fails a software engineer — but "30 of your 94 students could disappear from your count on Thursday" lands regardless of background.

The 2nd-person consistency requirement closes a gap the narrative-bleed detector only partially addresses. The detector checks the first sentence; the description body can still drift. "Dr. Voss has 48 hours" reads as a third-person narrator talking about a character — the player is watching, not deciding.

Alternatives Considered¶

Add a new Principle #14 for "comprehension test." Rejected in favor of expanding existing principles — the comprehension test is the operationalization of #5 and #10, not a new principle. Adding more numbered principles dilutes the attention given to each.
Add a post-generation comprehension validator that checks for specific jargon patterns. Rejected as too brittle — institutional vocabulary is too varied to enumerate. The prompt-side jargon test is more robust.
Fix "The Count" scenario directly in the database rather than fixing the generator. Rejected — the scenario was live-generated, not curated; fixing the instance doesn't fix the class.

Discussion¶

Institutional scenarios are a specific trap: they sound well-researched (real role names, real process names, real bureaucratic structures) and they pass all the structural validators (2nd-person opener, no banned headers, valid driver tags), but they're opaque to anyone outside the institution. The jargon test in Principle #10 is specifically aimed at this: "could a smart 28-year-old career-changer with no background in this field understand this?" If no, translate or replace.

The decision-prompt fix addresses a different failure mode: scenarios that end with a poetic frame ("the question is how you respond") rather than a concrete trigger. The frame version sounds sophisticated but leaves the player uncertain about what specifically happens next and when. The concrete version ("the Budget Committee meets Thursday at 9AM — if you don't move first, someone else frames this as a failing program") answers both questions and creates urgency.

These changes increase prompt length. The offset is that they add precision that reduces hallucinated-style outputs — the jargon test and comprehension test give the model a procedure rather than just an aspiration, which should produce more reliable compliance.

Consequences¶

All future generated scenarios carry a higher clarity bar: named worst cases, translated jargon, 2nd-person throughout, concrete decision prompts.
The curated scenario corpus is unaffected — existing scenarios are not automatically retroactively flagged, though the jargon test could be useful as an audit tool for a future pass.
Watch for: scenarios that become over-explained — too much exposition trading off against the 350-word limit. If scenarios start feeling like tutorials instead of dilemmas, tighten the word limit enforcement rather than removing the jargon test.
Related: the narrative-bleed detector still only checks the first sentence for 2nd-person. A validator for 3rd-person drift in the description body would be a complementary tool — not done here, but flagged as a follow-up if the prompt fix doesn't close the gap.

Key files: - src/lib/ai/scenario-generator.ts — Principles #1, #5, #10, and Voice & Format decision-prompt rule expanded