settled-reach/docs/design/divergent-starting-knowledge.md

Divergent Starting Knowledge

Ticket: #182 | Priority: Critical | Sprint: 12 Status: v0.1 Draft Blocked by: #180 (Smuggler build), #181 (Detective build) Decisions referenced: D-005 (asymmetric information), D-027 (vertical slice), D-041 (knowledge graph), D-065 (evidence display)

---

1. Design Principle

Asymmetric information is the master mechanic (D-005). The two characters know different things about the same world. Neither has the full picture. The game's central tension comes from each player discovering what the other already knew — but only on their second playthrough.

The knowledge sets are not merely different. They are inverted at the points that matter most. The smuggler knows the conspiracy from inside it. The detective knows the investigation from outside it. The middle — the social web that connects them — is what neither fully understands at session start.

---

2. Master Knowledge Comparison Table

2a. Contraband and Ring

Fact	Smuggler	Detective
Ring exists (organized smuggling operation)	KnowsEverything — member	Unknown — suspects "systematic manipulation" but no structural knowledge
Ring members (Nils, Kael, Voss, Renn, Devra, Resha)	KnowsDetails — works with them daily	Unknown — names absent from case file; only Voss, Maret, Drin as institutional POIs
Cargo type (unlicensed lattice components, medical replacements)	KnowsDetails — handles the containers	Unknown — case file has weight/size anomalies but not cargo type
Smuggling routes (corridor access, timing windows)	KnowsEverything — runs the routes	Unknown — knows maintenance corridors exist from district layout documents
Operation schedule (shift transition windows)	KnowsEverything — the 20-minute gaps are the job	KnowsDetails — case file shows anomaly clustering around shift transitions
Supply chain upstream (Sabel, Syndic connection)	KnowsOf (partial: knows Sabel, not the full chain)	Unknown
Voss's complicity (takes a cut, provides scheduling cover)	KnowsEverything — operational fact	Unknown — Voss is a POI because of scheduling authority, not proven complicity
Drin's complicity (looks the other way on inspections)	KnowsDetails — operational asset	Unknown — Drin is a POI because of inspection failures
Maret's awareness (scheduling access to cover for ring)	KnowsDetails — hub colleague	KnowsOf — person of interest from case file

2b. Investigation

Fact	Smuggler	Detective
Detective's identity as investigator	Unknown — may know "new Commission presence" from ring warning	KnowsEverything — is the investigator
Detective's actual mandate (investigate freight irregularities)	Unknown — "routine compliance review" is the cover	KnowsEverything
Manifest discrepancies exist and are flagged	KnowsOf — operational awareness that paperwork is being managed	KnowsDetails — has the discrepancy data, cluster analysis, container series
Previous Commission liaison rotation (possibly arranged)	Unknown	KnowsOf — noted in case file as suspicious; unconfirmed
Commission's investigation timeline	Unknown	KnowsDetails — their own timeline

2c. Key People

Fact	Smuggler	Detective
Kael's exit attempt (unauthorized external contact)	Unknown (CRITICAL gap — basis for FRIEND arc)	Unknown
Sera's unreported evidence (suppressed compliance check on Kael)	Unknown	Unknown (CRITICAL gap — basis for FRIEND arc)
Naia confided in Sera about Kael	Unknown	Unknown
Naia's worry about Kael's behavior	KnowsOf — has noticed Naia seems stressed at bar; doesn't know why	Unknown — Naia is not yet a known individual
Torek's spending (conspicuous, potential security risk)	KnowsOf — has noticed; worries about exposure	KnowsOf — "slightly off in a way I can't yet articulate"
Sera's background (pre-existing contact for detective)	Unknown — knows Sera only as "Commission, keep distance"	KnowsDetails — trusted pre-existing friend
Smuggler's role in the ring	KnowsEverything — is a member	Unknown — one of many dock workers
Kael's relationship with Nils (brother; ring coordinator)	KnowsDetails	Unknown

2d. Location and World

Fact	Smuggler	Detective
Sova Transit District geography (full)	KnowsEverything — 3 years here	KnowsOf — 3 days; still orienting
Corridor B-7 (restricted, ring access)	KnowsEverything — knows the access token, uses the corridor	Unknown — maintenance corridors noted in district layout
Dead drop location (temp storage bay 4, container 4471)	KnowsEverything	Unknown — container 4471 appears in manifest discrepancy data but not mapped to a location
Shift schedule rhythms (social and operational)	KnowsEverything	KnowsOf — knows shifts exist, pattern from case file
Bar social structure (who sits where, who's a regular)	KnowsDetails — 2 years of evenings at Lera's	KnowsOf — has visited twice

---

3. Knowledge Asymmetry Map

The gaps in each character's knowledge are not random — they cluster around the same events and people, approached from opposite directions:

                     THE SHARED WORLD
                           ↕
         ┌─────────────────────────────────────┐
         │           Triangle 4                │
         │    Naia ←→ Kael ←→ Sera            │
         │     ↑              ↑               │
         │  (Kael's       (suppressed         │
         │  partner,      evidence)           │
         │  knows          ↕                  │
         │  something)   Detective's          │
         │     ↕         FRIEND               │
         │  Smuggler's                        │
         │  FRIEND                            │
         └─────────────────────────────────────┘

Smuggler knows: Kael (trusted friend), ring details, routes, members
Smuggler doesn't know: Kael is exiting, Sera's evidence, Naia→Sera connection

Detective knows: Investigation data, Sera (trusted friend), manifest anomalies
Detective doesn't know: Ring structure, Kael's role, Sera's evidence, Naia→Sera connection

Neither knows: Triangle 4's full shape — the chain from Naia's worry to Sera's suppression to the investigation closing in

The dramatic irony of the second playthrough is that the player who's played as the smuggler watches the detective investigate from outside what the smuggler knows intimately. The player who's played as the detective watches the smuggler trust Kael — not knowing the thing the detective now knows (Kael is the link between the ring and Sera's evidence).

---

4. Knowledge Acquisition Curves

Smuggler: What they can learn, and how

Unknown → Known	Method	Timing
Detective's identity	Ring warning (Kael/Voss mentions Commission presence) OR direct observation	Minutes 0-5 (if warned); later if not
Kael's exit attempt	THE FRIEND arc — spatial observation (Corridor B-7), then confrontation	Minutes 15-25
Sera has unreported evidence	Cannot discover this through normal play. Would require Sera to confess or Naia to reveal — extreme late-game territory beyond v0.1 scope	Post-v0.1
Torek's specific risk level	Observation of Torek's behavior over time	Minutes 10-20

Detective: What they can learn, and how

Unknown → Known	Method	Timing
Ring exists (structured)	Evidence accumulation — NPC behavioral tells, manifest patterns, corridor observation	Minutes 15-25
Kael is ring member	Connecting manifest discrepancies to Kael's shift data; cargo attention tell	Minutes 20-30
Sera's unreported evidence	THE FRIEND arc — behavioral pattern observation (Torek avoidance), then confrontation	Minutes 20-30
Smuggler is in the ring	Tell accumulation (corridor check, social clustering with Kael/Renn), manifest connection	Minutes 15-30
Kael's exit attempt	Would require Kael to confess or Naia to reveal — beyond normal investigation path	Post-confrontation branch

---

5. Evidence Display Difference

Same underlying Knowledge Graph, different presentation layer (D-065):

Detective — Case File Format:

Entity: Kael Davan
Role: Dock worker, Sova Terminal
Confidence: KnowsOf
Source: observation
Attributes:
  - routine_pattern: "morning shift 06:00-14:00"
  - behavior_flags: [lattice_checking, shortened_interactions]
  - risk_assessment: "moderate — behavioral anomalies suggest concealment"
  - link: [manifest_discrepancy_cluster_A]
Insert suggests: "Check shift records against anomaly window"

Smuggler — Personal Notebook Format:

Kael — closes colleague, ring. Two years. Trust: solid.
Lately: distracted. Lunch cut short twice this week.
Something's off. Not the operation — personal.
Watch for: the look-left tell.

Same underlying entity. Different framing. The detective files evidence. The smuggler worries about people.

---

6. Design Implications for Content Authors

Rule 1: Don't explain what the character already knows. The smuggler doesn't need exposition about how the ring works. They know. Monologue lines about the ring should be operational, not explanatory. The detective doesn't need exposition about institutional procedures. They know. Monologue lines about the investigation should be observational, not procedural.

Rule 2: The unknown facts are load-bearing. When writing monologue lines, verify against the unknown_facts list. A smuggler monologue line that references Kael's exit attempt before Phase 3 is a continuity error. A detective monologue line that identifies Kael as a ring member before connecting manifest data to shift records is a continuity error.

Rule 3: Knowledge gaps produce monologue, not silence. What a character doesn't know generates JUST AS MUCH monologue content as what they know. The smuggler's worry about "is Torek a risk?" is monologue material. The detective's uncertainty about "previous liaison rotation — arranged or routine?" is monologue material. The unknown is active, not empty.

Rule 4: The same event produces inverted monologue. When the same NPC does the same thing in both playthroughs, the monologue responses should be detectably from different starting states. Kael checking his lattice → smuggler thinks "not like him to be jumpy" (personal familiarity) → detective thinks "lattice activity spiked, behavioral flag" (observational analysis).

---

Ticket #182 — Divergent starting knowledge. v0.1 scope.