settled-reach/docs/design/mirror-moment-design.md

title, description, type, status, ticket, decision_refs, author, created, updated, superseded_by

title	description	type	status	ticket	decision_refs	author	created	updated	superseded_by
Mirror Moment Design Document	Seven core mirror moments where the same trigger fires different monologue for smuggler and detective	design	superseded	#329	D-032 D-034 D-039		2026-02-19	2026-02-19	D-122

SUPERSEDED (2026-06-12, cascade-refocus sweep): superseded by D-122 (no named characters) + D-132 (consequence replaces the complicity frame). Kept as historical record; do not build against it.

Mirror Moment Design Document

Ticket: #329 Owners: Gestalt (framework + specs), Paula + Mellanie (line authoring) Source: D-032 (separate monologue pools), D-034 (FRIEND pattern), D-039 (wow moments) Date: 2026-02-19

---

What Is a Mirror Moment

A mirror moment is a shared trigger that fires different monologue for each playable character.

Same event. Same tile position. Different observation. The smuggler and the detective see the same thing and think completely different thoughts. Neither perspective is wrong. Neither is complete.

The dramatic irony is the point. On first playthrough, you get one lens. On replay as the other character, you revisit the same moment and understand what the other character was thinking. The world you thought you understood had another interpretation the whole time.

---

Mechanics

How mirrors work (D-032)

Monologue pools are hard-partitioned by character tag. Same trigger fires two different pools — one for the smuggler, one for the detective. The engine selects from the appropriate pool based on which character is playing.

# Same trigger, two pools — the mirror
- id: example_mirror_s_001
  character: smuggler
  trigger: observe_npc          # Trigger condition
  text: "Smuggler's interpretation of the event"
  tags: [mirror, the-friends-routine]

- id: example_mirror_d_001
  character: detective
  trigger: observe_npc          # Same trigger condition
  text: "Detective's interpretation of the same event"
  tags: [mirror, the-friends-routine]

Mirror vs. standard monologue

Standard monologue: fires for any character, addresses the environment from their general perspective. Mirror: intentionally paired — the contrast between the two lines IS the content.

Not every environmental line needs a mirror. Most monologue is character-specific without being a deliberate paired contrast. Mirrors are designed — each one has a specific dramatic irony that pays off on replay.

Prerequisite considerations

Mirror moments can have prerequisites that differ by character. The smuggler sees Kael's routine as familiar. The detective sees the same routine as data. But both must be able to encounter the trigger — prerequisite design should not lock one character out of a mirror unless that's intentional.

---

The Seven Core Mirrors

Mirror 1: The Friend's Routine

Trigger: observe_npc — observe Kael Davan at the beginning of his shift (dock floor, Phase 1 timing)

Dramatic irony: The smuggler sees their most trusted colleague. The detective sees a dock worker with flagged manifests.

Character	Monologue Register	Key Emotional Note
Smuggler	Warm recognition, ease, competence acknowledged	"The day's better when Kael's on shift"
Detective	Clinical observation, professional assessment	"Davan. He's the one on three of the flagged manifests"

Prereqs:

• Smuggler: none — fires on game start
• Detective: suspects: investigation.manifest_discrepancy (has flagged the anomaly)

Payload on replay: The detective's cool assessment of "the one on three flagged manifests" lands differently when you've played the smuggler and know Kael is your most trusted friend.

---

Mirror 2: The Empty Corridor

Trigger: enter_location — enter Corridor B-7 (maintenance corridor, restricted zone)

Dramatic irony: The smuggler knows this place. The detective is piecing it together.

Character	Monologue Register	Key Emotional Note
Smuggler	Operational familiarity — this is a work space	"Quiet tonight. Route's clear. Move."
Detective	Investigative alertness — spatial reasoning about why this corridor	"This shouldn't connect to the main dock flow. Someone redesigned the access."

Prereqs:

• Smuggler: knows_details: knowledge.ring_routing_knowledge (always true — background knowledge)
• Detective: none — first-time observation lines for arrival; suspects: investigation.manifest_discrepancy for more specific reads

Payload on replay: The detective's spatial analysis ("someone redesigned the access") is exactly what the smuggler takes for granted — someone DID redesign it, to create the drop route.

---

Mirror 3: The Worried Partner

Trigger: observe_npc — observe Naia Tamm at The Last Shift (bar, first encounter)

Dramatic irony: The smuggler knows exactly why Naia looks worried — she's worried about Kael, and the smuggler knows why Kael is distracted. The detective sees a civilian who might be a useful connection.

Character	Monologue Register	Key Emotional Note
Smuggler	Guilt-adjacent recognition — knows more than Naia does	"Naia. She's got that look — the one she gets when Kael's not telling her something."
Detective	Analytical warmth — potential social anchor, reads the worry	"Someone waiting for someone who's late. Or someone carrying something they can't put down."

Prereqs:

• Smuggler: knows: relationship.kael_naia_connection (learns through background or Kael references)
• Detective: none — fires on first observation of Naia

Payload on replay: The detective's "someone carrying something they can't put down" is unknowingly accurate — Naia is carrying worry about Kael that she can't voice. The smuggler knew the source.

---

Mirror 4: The Spending

Trigger: observe_npc — observe Torek Lintar at The Last Shift during a spending moment (rounds for the bar, visible display)

Dramatic irony: The smuggler sees an operational risk — someone advertising that they have more money than they should. The detective sees the investigation materializing.

Character	Monologue Register	Key Emotional Note
Smuggler	Operational caution — this is how you get caught	"Torek's buying rounds again. Someone needs to say something. This is how you draw attention."
Detective	Investigative recognition — the pattern confirms	"There it is. Dock inspector, mid-pay-grade, buying rounds at a freight bar. Where does that come from?"

Prereqs:

• Smuggler: none — fires on observation (smuggler intuits operational risk)
• Detective: suspects: investigation.torek_spending_pattern (has noticed the pattern beginning)

Payload on replay: The smuggler's exasperation ("this is how you get caught") is exactly what eventually happens — Torek's spending is how the detective builds the case.

---

Mirror 5: Sera Leaving

Trigger: witness_interaction — observe Sera Venn abruptly leave the bar when Torek Lintar arrives (The Last Shift)

Dramatic irony: This is the core Sera contradiction trigger for the detective. For the smuggler, it's just a Commission woman who doesn't like Torek — plausible, not significant.

Character	Monologue Register	Key Emotional Note
Smuggler	Mild observation, dismissive — not their circle	"Commission woman doesn't like Torek. Smart. He's loud."
Detective	Pattern recognition accumulating — third observation fires the arc	"Three times. Same exit, three different reasons. That's not personality — that's data."

Prereqs:

• Smuggler: none — fires on any observation of the departure
• Detective (Phase 3): fires specifically on third observed departure — the contradiction completes

Notes: This mirror has asymmetric emotional weight by design. For the smuggler it's noise; for the detective it's the arc-completion moment. The contrast is the dramatic irony — on replay as the detective, you understand why the same moment that was nothing to the smuggler was everything to the detective.

---

Mirror 6: The Hum

Trigger: hear_sound — hear the span gate harmonics (ambient sound in the Transit District, audible near the gate)

Dramatic irony: The smuggler hears the operational heartbeat — the gate timing is part of their work. The detective hears institutional infrastructure that someone is exploiting.

Character	Monologue Register	Key Emotional Note
Smuggler	Operational familiarity — rhythmic, known, workable	"Gate cycle. Twenty-two minutes before the next transit window. Plenty of time."
Detective	Analytical listening — patterns reveal structure	"The gate schedule has a window. Someone's using it. You don't exploit something this consistent by accident."

Prereqs:

• Smuggler: none — fires on any span gate sound observation
• Detective: suspects: investigation.manifest_discrepancy (has the anomaly, is building the picture)

Payload on replay: The detective's "you don't exploit something this consistent by accident" is confirmed by the smuggler's casual knowledge of the transit window timing.

---

Mirror 7: The Commission Kiosk

Trigger: observe_npc — observe Sera Venn at the Commission calibration kiosk (Level 3, morning diagnostics routine)

Dramatic irony: The smuggler sees Commission presence and reads it as operational risk. The detective sees their closest ally doing their job — and then maybe something else.

Character	Monologue Register	Key Emotional Note
Smuggler	Caution, professional distance — Commission means danger	"Commission tech running diagnostics. Stay normal. She's doing her job. Let her do it."
Detective	Fond recognition shifting to observation	"Sera, running morning rounds. Same time, same kiosk. She always is. ...Why does she stay so long?"

Prereqs:

• Smuggler: none — fires on any Sera observation (context-adjusted by Phase)
• Detective: knows: behavioral.sera_kiosk_pattern fires the extended-time observation variant

Payload on replay: The smuggler's "let her do her job" — not knowing that Sera ISN'T just doing her job, she's compulsively rechecking compliance data to make sure she hasn't been caught — reframes the detective's late-game worry ("why does she stay so long?").

---

Authoring Guidelines

What makes a mirror effective

1. Asymmetric depth. One character has more context than the other. The better-informed read is more specific; the less-informed read is still true — just incomplete. Neither is wrong.

2. The replay payoff is the point. Write both lines imagining the player who knows both perspectives. The goal is the recognition moment: "Oh — that's what they were thinking."

3. Same emotional register is wrong. If both characters sound the same, it's not a mirror — it's two generic observations. The characters must feel differently about the same trigger.

4. Don't editorialize. Neither character says "little did I know..." or provides retrospective framing. They speak in the moment, from their knowledge state. The irony emerges from context, not from the line itself.

Trigger selection

Mirror moments work best on triggers that are:

• Routine — something that recurs throughout the session, so both characters naturally encounter it
• Spatially available to both — the smuggler and detective both operate in the three social sites
• Emotionally loaded differently — the same object/person/sound has different resonance depending on your knowledge

Triggers to avoid for mirrors:

• One-time scripted events (both characters might not see them)
• Confrontation triggers (those are character-specific by design)
• Lines gated so heavily by prerequisites that one character rarely sees them

Line count per mirror

Each core mirror: 2-4 lines per character — variations on the same observation for different confidence states or visit counts (e.g., first visit, return visit).

Total for 7 core mirrors: approximately 28-56 lines (14-28 per character), spread across trigger types.

Paired notation for authors

When authoring mirror lines, use dual_lens authoring note to document the contrast:

- id: mirror_7_s_001
  character: smuggler
  trigger: observe_npc
  text: "Commission tech running diagnostics. Stay normal. She's doing her job. Let her do it."
  tags: [mirror, the-commission-kiosk]
  dual_lens:
    smuggler: "Defensive distance — Commission means risk, avoid attention"
    detective: "Same NPC as the detective's FRIEND — the contrast is that the smuggler dismisses exactly what the detective is learning to doubt"
  notes: "Paired with mirror_7_d_001"

---

Organic Mirrors (3-5 to discover during content review)

During Mellanie's content pack authoring (#190, #191, #192), additional mirror moments will emerge organically when the same environmental element naturally reads differently for each character. Authors should flag these with [MIRROR CANDIDATE] in comments.

Likely candidates:

• Voss giving shift assignments (the smuggler reads operational signaling; the detective reads management as cover)
• Kael at lunch (the smuggler reads normalcy; the detective reads behavioral data)
• Lera serving a regular order (the smuggler reads social comfort; the detective reads access patterns)
• The empty bay at shift transition (the smuggler reads operational window; the detective reads anomalous access pattern)

These become confirmed mirrors after both character packs are written — identify paired lines that emerged independently, then strengthen the contrast deliberately.

---

Integration with Content Authoring

For Mellanie (#190, #191, #192 content packs)

When authoring NPC-observation and environmental lines, flag any line that:

• Involves a character or location that is significant to both the smuggler and detective
• Would read differently depending on what the observing character knows
• Contains a detail that is loaded for one character but neutral for another

Flag format: add [MIRROR CANDIDATE: {brief description of the contrast}] as an authoring note.

For Paula (#299, #300 opening hooks)

Opening hook content should include at least 2-3 mirror moments from the Core 7 above. The smuggler's arrival at the Terminal should establish The Friend's Routine (Mirror 1) and may include The Hum (Mirror 6). The detective's arrival should include Mirror 1 (from their clinical perspective) and Mirror 5 setup (Sera present in bar).

Prerequisite cross-reference

All mirror moment prerequisite fact IDs are defined in: docs/design/knowledge-flags-v01.md

---

Design document. Core 7 mirrors are confirmed and spec'd. Organic mirrors (3-5) to be identified during content authoring. Line authoring: Mellanie + Paula. Framework: Gestalt.