diff --git a/DECISIONS.md b/DECISIONS.md index 4a4f0c30b..e5dee2038 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -329,6 +329,21 @@ This document tracks confirmed decisions, open questions, and rejected alternati - **Raised by:** Gore (thematic), Paula (30/50/20 split), Nigel (anti-metagaming), Team Leader (majority unentangled) - **Dissent:** None +### D-030: Testability architecture — 8 decisions for ticket #214 +- **Date:** 2026-02-11 +- **Decision:** The v0.1 testability architecture is confirmed with 8 sub-decisions from the Gap Analysis Workshop (Round 18): + 1. **Rust test organization = Hybrid.** `#[cfg(test)]` for unit tests inside modules + `tests/` directory for integration tests. Both via `cargo nextest run`. + 2. **Godot test framework = gdUnit4** (changed from GUT). Native JSON output, stable headless via `GdUnitCmdTool`, `GdUnitSceneRunner` for scene lifecycle tests, organizational maintenance. + 3. **IPC testing = Three-layer architecture.** Layer 1: fixture-based serialization roundtrip (fast, every edit). Layer 2: mock subprocess protocol state machine (medium, every PR). Layer 3: real subprocess integration (slow, daily/pre-merge). + 4. **Production code constraints + CauseChain.** No `#[cfg(test)]` in production. Public API is the test surface. ECS World setup replaces mock injection. CauseChain is a production component (monologue provenance, journal, debugging) that tests also leverage. + 5. **Test runner tooling.** `cargo-nextest` (Rust) + gdUnit4 (Godot) + bash wrapper scripts in `test/` directory, whitelistable for agent use. + 6. **Test output format = JSON summary.** Consistent schema across all runners (suite, total, passed, failed, failures array). JUnit XML as secondary CI format. + 7. **#201 (Deterministic replay) promoted to CRITICAL.** Simulation must consume time, randomness, and input exclusively through injectable resources (`SimulationTime`, `SimRng`, `InputQueue`). Required by D-010 principle 4. + 8. **Test priority aligned with hard blockers.** Phase 1 (sprint 1-2): test infra + collision/pathfinding/time. Phase 2 (sprint 3-4): monologue pipeline integration test + information boundary negative tests. Phase 3 (sprint 5+): CauseChain verification + divergent snapshots. +- **Rationale:** Two rounds of analysis by Tyre (Technical Architect) and Hoshe (QA Engineer) with cross-validation from all design agents. Key change: gdUnit4 over GUT driven by agent-driven development requirements (JSON output, headless stability, bus factor). CauseChain endorsed unanimously after all design agents independently identified the need for information provenance tracking. +- **Raised by:** Tyre (architecture), Hoshe (testability analysis). Full workshop endorsed. +- **Dissent:** GUT vs gdUnit4 resolved in Hoshe's favor — Tyre explicitly changed position. No remaining dissent. + ### D-004: Team composition confirmed - **Date:** 2026-02-08 - **Decision:** Team of 8 agents + Team Leader. @@ -445,4 +460,4 @@ This document tracks confirmed decisions, open questions, and rejected alternati --- -*Document maintained by QATUX. Last updated: 2026-02-10* +*Document maintained by QATUX. Last updated: 2026-02-11* diff --git a/docs/discussions/README.md b/docs/discussions/README.md index 825a2f5ba..64368b769 100644 --- a/docs/discussions/README.md +++ b/docs/discussions/README.md @@ -21,3 +21,4 @@ Historical discussion rounds from the Commonwealth game design process. | 15 | README / Steam Page Placeholder | - | [round-15](round-15-readme-steam-page.md) | | 16 | Factions — Building a Fuller Narrative Picture | AWAITING INPUT | [complete](round-16-factions-complete.md), [lore](round-16-factions.md), [mechanics](round-16-faction-mechanics.md), [notes](round-16-session-notes.md) | | 17 | Content Architecture | D-023, D-024, D-025, D-026, D-027, D-028, D-029 | [round-17](round-17-content-architecture.md) | +| 18 | v0.1 Gap Analysis Workshop | D-030 | [round-18](round-18-v01-gap-analysis-workshop.md) | diff --git a/docs/discussions/round-18-v01-gap-analysis-workshop.md b/docs/discussions/round-18-v01-gap-analysis-workshop.md new file mode 100644 index 000000000..9c319d1fa --- /dev/null +++ b/docs/discussions/round-18-v01-gap-analysis-workshop.md @@ -0,0 +1,517 @@ +# ROUND 18: v0.1 Gap Analysis Workshop + +**Date:** 2026-02-11 +**Type:** Two-round structured workshop +**Participants:** Gestalt, Ozzie, Paula, Gore, Nigel, Tyre, Hoshe (7 agents) +**Facilitator:** Team Leader (Jeroen) +**Documenter:** Qatux + +--- + +## 1. Workshop Summary + +### Purpose + +Stress-test the existing 232-ticket v0.1 plan against six concept proof claims derived from D-005, D-027, and the game's core design pillars. Identify gaps between what the ticket plan builds and what the v0.1 must prove. + +### Structure + +**Round 1 — Independent analysis.** Each agent worked their assigned tracks without seeing other agents' responses: + +| Track | Focus | Assigned Agents | +|-------|-------|----------------| +| Track 1: Concept Proof | Rate 6 claims against ticket coverage | Gestalt, Ozzie, Paula, Nigel, Gore | +| Track 2: Fun/Wow Gap | Identify missing moments and emotional delivery | Gestalt, Ozzie | +| Track 3: Missing Things | Identify unticketed hard/soft blockers | Gestalt, Tyre | +| Track 4: Testability | Finalize testability decisions for #214 | Tyre, Hoshe | + +**Round 2 — Cross-pollination and synthesis.** All agents read all Round 1 responses. Each responded to insights from other agents, revised positions, and consolidated proposals. + +### Six Concept Proof Claims + +1. **Asymmetric information** — "You only know what your character knows" +2. **Fog of perception** — "Fog = tension, not just fog of war" +3. **NPCs feel alive** — "NPCs have lives, relationships, and secrets you can discover" +4. **Observation as mechanic** — "Watching, listening, and following ARE the gameplay" +5. **Same world, different story** — "Two characters experience fundamentally different games" +6. **Social triangles** — "Overlapping NPC relationships create player decisions" + +### Key Outcome + +The ticket plan builds strong infrastructure but has a systematic gap in the **experience layer** — the systems that translate simulation data into player-felt moments. The workshop produced 33 new consolidated tickets, 14 priority promotions on existing tickets, 8 testability decisions, a narrative authoring specification, and a unifying design thesis. + +--- + +## 2. Concept Proof Scorecard + +### Consolidated Risk Assessment + +Each agent rated the six claims from their domain expertise. Risk levels below represent the workshop consensus after Round 2 synthesis. + +| # | Claim | Infrastructure | Experience Layer | Consensus Risk | Primary Gap | +|---|-------|---------------|-----------------|----------------|-------------| +| 1 | Asymmetric information | STRONG — info boundaries (#138-142), ObserverSnapshot | Interpretation missing — characters see different data but don't THINK differently | **MEDIUM-HIGH** | Identity-driven monologue interpretation | +| 2 | Fog of perception | STRONG — shadowcasting (#110-113), sound (#124-128), vision cone | Deviation detection missing — fog is spatial but not experiential | **LOW-MEDIUM** | Routine deviation detection system | +| 3 | NPCs feel alive | STRONG — 10-axis model (D-024), routines (#88, #101), simulation tiers (D-026) | Discovery mechanisms missing — NPCs live but players can't observe their lives | **MEDIUM-HIGH** | Observation event pipeline, pathfinding | +| 4 | Observation as mechanic | PARTIAL — perception systems exist | Player verbs missing — no follow, examine, interact dispatcher | **HIGH** | Player interaction system, observation event generator | +| 5 | Same world, different story | PARTIAL — divergent knowledge (#182-183) | Narrative arcs underspecified — different facts but not different MEANINGS | **HIGH** | Interpretive framing, Perspective and Arc authoring spec | +| 6 | Social triangles | PARTIAL — triangle generation (#106-109) | Activation/resolution missing — triangles exist as data but never fire | **HIGH** | Triangle escalation system, tolerance thresholds (#105) | + +### The Pattern + +Gestalt identified the defining pattern: **infrastructure is systematically strong; the experience layer is systematically missing.** Every claim has solid data models and simulation systems. What's absent is the layer that translates simulation state into observable, interpretable, emotionally resonant player moments. The observation event generator — where perception, knowledge, identity, and monologue converge — is the mechanical heart of this missing layer. + +### Individual Scorecards + +**Gestalt (Systems Design):** Rated all 6 claims on systemic coverage. Top risks: no player interaction verbs (Claim 4), no triangle activation mechanism (Claim 6). Identified 5 systemic risks including time system (Q-009) unresolved. + +**Ozzie (Player Experience):** Dual-scored each claim on systemic (1-5) and emotional (1-5) delivery. Overall emotional average: 3.2/5 (revised down from 3.3 in Round 2 after Paula's insight on Claim 5). Key finding: "NOTICING THAT AN NPC BROKE THEIR ROUTINE IS THE CORE GAMEPLAY LOOP AND IT'S NOT A TICKET." + +**Paula (Narrative):** Three-dimensional rating: mechanical coverage, narrative delivery, emotional resonance. Claim 5 rated highest risk — "the weakest claim despite being the most important." Pattern: tickets build strong mechanical foundations but underspecify narrative connective tissue. + +**Gore (Themes):** Unified all 6 claims under one thesis (see Section 3). Distinguished load-bearing moments (thesis-proving) from important-but-not-load-bearing moments (fun-proving). Three thematic priorities: interpretive divergence, recontextualization, quiet life has meaning. + +**Nigel (Replayability):** Rated each claim for 3rd+ playthrough value. Round 1 scores: 4-6/10 range. Round 2 revised scores: 6-8/10 with experience layer systems added. Key insight: the experience layer IS the replayability layer. + +--- + +## 3. Core Thesis + +### "Who you are determines what is real" + +**Proposed by:** Gore (Round 1) +**Endorsed by:** Full workshop (Round 2) + +Gore unified all six concept proof claims under a single thesis: the game's central argument is that identity shapes perception, and perception constructs reality. All six claims are facets of this thesis: + +- **Asymmetric information** = different knowledge bases +- **Fog of perception** = different spatial awareness +- **NPCs feel alive** = different relationships to the same people +- **Observation as mechanic** = different salience filters +- **Same world, different story** = different interpretive frames +- **Social triangles** = different stakes in the same conflicts + +**Mechanical expression:** The observation event generator (see Section 5, C-4) must query character identity when generating events — not just "what does the character KNOW?" but "what does the character CARE ABOUT?" The smuggler's knowledge base makes criminal activity salient. The detective's makes institutional anomalies salient. Same NPC behavior, different observation events, different monologue, different reality. + +**Nigel's extension:** "Who you are determines what is real. And what is real changes every time." Character variation provides depth (different realities). Seed variation provides breadth (different worlds). Both axes are required. + +**Gore's scoping for v0.1:** The vertical slice must prove **Thesis A** (identity is perspectival — same seed, different character, different reality). **Thesis B** (reality is contingent — different seeds change the world) reinforces Thesis A but is a secondary proof. + +**Design implication (Gestalt):** Every system in the experience layer needs an identity-aware interpretation step. The observation event generator, follow mechanic, examine mechanic — all must be colored by character identity, not generic. + +--- + +## 4. Fun/Wow Gap Analysis + +### Ozzie's Assessment + +Ozzie identified a systematic gap between simulation capability and emotional delivery. The ticket plan builds the machine; it doesn't design the moments. + +**Missing moment categories:** + +| Gap | Description | Impact | +|-----|-------------|--------| +| **No observation event pipeline** | Perception systems exist but nothing connects "player sees NPC" to "character interprets and comments." The spine of the game is spread across 4 epics with no connecting tissue. | Without this, the player sees things but doesn't understand them. | +| **No routine deviation detection** | NPCs have routines but no system detects when they break routine. The core detective mechanic doesn't exist as a ticket. | Without this, investigation has no entry point. | +| **No first-5-minutes design** | No opening hook, no diegetic objective, no "here's why you should care." The player spawns and stands there. | First impression determines whether players keep playing. | +| **No opening monologue** | The character has no voiced reaction to their starting situation. | Missed opportunity for the cheapest, highest-impact atmosphere moment. | +| **No tell visual expression** | NPC behavioral tells (D-024) have no defined visual/behavioral manifestation in the top-down renderer. | Observation chain has no starting point — can't notice what you can't see. | +| **No triangle escalation events** | Triangles exist as data but never produce observable drama. | Social system is backstory, not gameplay. | + +**The 30-second demo moment (Ozzie):** Fog + NPC + monologue + routine deviation + "Should I follow her?" — this sequence requires all five of Tyre's hard blockers (collision, pathfinding, time, interaction, NPC movement) to work, plus the observation event pipeline, plus monologue integration. It is the minimum viable proof of concept. + +**First 5 Minutes rating:** 2/5 for design, 0/5 for implementation without Tyre's infrastructure blockers resolved. + +**Gore's ethical dimension as wow multiplier:** The detective overhearing a private conversation through a wall fires monologue: *"She doesn't know I can hear this."* This delivers information, atmosphere, AND ethical texture simultaneously. Ozzie endorsed: "Gore's ethical dimension is a wow MULTIPLIER, not a wow complicator." Rule for content authoring: the character notices they're watching; they don't moralize. The PLAYER does the moralizing internally. + +--- + +## 5. Missing Ticket List + +### Gestalt's Consolidated Proposal + +Gestalt consolidated 49 proposals from 7 agents into 33 new tickets, eliminating 16 duplicates through merging (33% dedup rate). The observation event generator alone absorbed 5-6 independently proposed tickets. + +### CRITICAL Priority (5 tickets) + +| ID | Title | Absorbs | Source Agents | +|----|-------|---------|--------------| +| C-1 | Tile collision system | -- | Tyre | +| C-2 | Tile-based A* pathfinding + NPC movement (2 stories in 1 epic) | Tyre's pathfinding + NPC path following; Gestalt's NPC pathfinding | Tyre, Gestalt | +| C-3 | Game clock and day-phase system (resolves Q-009) | Tyre's game clock; Gestalt's time system concern | Tyre, Gestalt | +| C-4 | Observation event generator (with deviation detection) | Ozzie's observation event pipeline + routine deviation detection; Paula's absence detection + knowledge-aware monologue integration; Gestalt's NPC off-routine behavior | Ozzie, Paula, Gestalt | +| C-5 | Player interaction system + dispatcher | Gestalt's player interaction framework; Tyre's interaction dispatcher | Gestalt, Tyre | + +### HIGH Priority (14 tickets) + +| ID | Title | Source Agents | +|----|-------|--------------| +| H-1 | Follow mechanic | Gestalt | +| H-2 | Examine mechanic | Gestalt | +| H-3 | Triangle dynamics: escalation, activation, resolution | Ozzie, Paula, Gestalt | +| H-4 | NPC-to-NPC conversation system | Gestalt | +| H-5 | NPC player-awareness behavior | Gestalt | +| H-6 | Player-action social propagation | Paula, Nigel | +| H-7 | Tell visual/behavioral expression | Paula, Ozzie | +| H-8 | Character objectives, arcs, and pressure framework | Gestalt, Paula | +| H-9 | Opening experience design per character | Gestalt, Ozzie | +| H-10 | Monologue content architecture | Gestalt, Paula, Gore | +| H-11 | Contamination activation mechanic (simplified v0.1 storyteller) | Gestalt | +| H-12 | Client audio manager and spatial playback | Tyre | +| H-13 | Placeholder art specification | Tyre | +| H-14 | Save state data model and serialization | Tyre | + +### MEDIUM Priority (11 tickets) + +| ID | Title | Source Agents | +|----|-------|--------------| +| M-1 | Wait/time-skip mechanic | Gestalt | +| M-2 | Basic environmental interaction (doors, objects) | Gestalt | +| M-3 | Environmental text content (signs, terminals, documents) | Gestalt | +| M-4 | Knowledge/journal display (client) | Tyre | +| M-5 | Save/load game flow (client) | Tyre | +| M-6 | Game session management | Tyre | +| M-7 | Time display on insert HUD | Tyre | +| M-8 | Demo scenario specification (2-minute showcase) | Ozzie | +| M-9 | False positive NPC design (anti-metagaming) | Nigel | +| M-10 | Same-character-different-seed validation test | Nigel | +| M-11 | Playtest protocol definition | Hoshe | + +### Testing-Specific Tickets (3 tickets) + +| ID | Title | Priority | Source | +|----|-------|----------|--------| +| T-1 | Information boundary negative test suite | High | Hoshe | +| T-2 | CauseChain component for information events | High | Hoshe | +| T-3 | Test output formatter CLI | Low | Hoshe | + +### Totals + +- 49 original proposals across 7 agents +- 16 absorbed through merging (33% dedup rate) +- **33 consolidated new tickets** +- Split: 5 Critical, 14 High, 11 Medium, 3 Testing + +--- + +## 6. Priority Adjustments + +### Consensus Promotions on Existing Tickets + +14 priority promotions where 2+ agents independently recommended the change. Listed by consensus strength. + +| Ticket | Current | Recommended | Agents Recommending | Rationale | +|--------|---------|-------------|--------------------|-----------| +| **#103** Relationship dynamics | Medium | **HIGH** | Paula, Gestalt, Ozzie | Required for triangle activation, NPC attachment, Moment 3 (Cost of Knowing). Without this, no NPC feels like a person who changes. | +| **#105** Tolerance threshold triggers | Medium | **HIGH** | Paula, Gestalt, Ozzie | The only trigger mechanism for triangle escalation. Without it, triangles are backstory, not drama. | +| **#171** Trust-gated gossip | Medium | **HIGH** | Paula, Ozzie | Where daily life becomes interesting. 30-minute sustainer. Without gossip, social life is surface-level greetings. | +| **#172** Unprompted disclosure | Medium | **HIGH** | Paula, Ozzie, Gestalt | NPC-initiated story moments, off-screen event narration. Makes NPCs feel like they have agendas. | +| **#121** Character voice variation | Medium | **HIGH** | Gore, Ozzie, Gestalt | Must be scoped as INTERPRETIVE FRAMING, not just tonal variation. The mechanical expression of "who you are determines what is real." | +| **#178** Seed-based variation | LOW | **HIGH** | Nigel, Gestalt, Ozzie | Without it, replay ceiling = 2 playthroughs. With it: 10-12. The replayability engine. | +| **#102** Mood system | Medium | **HIGH** | Gestalt | Affects dialogue selection (D-028), NPC believability. | +| **#126** Medium-range visual indicators | Medium | **HIGH** | Ozzie, Gestalt | Fog-edge tension — hearing things you can't see. | +| **#108** Cross-template triangles | Medium | **HIGH** | Nigel, Gestalt | Source of the most surprising emergent stories. Different cross-template configs per seed. | +| **#175** Entanglement ratio config | Medium | **HIGH** | Nigel | D-029 anti-metagaming requires implementation. Variable per seed. | +| **#176** NPC pool generation | Medium | **HIGH** | Nigel | Per-seed NPC assignment is foundational for variation. | +| **#173** Trait modifier system | Medium | **HIGH** | Paula | Required for seed-variation narrative depth. Role archetypes without trait modification produce identical delivery. | +| **#182** Divergent starting knowledge | HIGH | **CRITICAL** | Nigel | Core differentiator between characters. Gore's "different realities" starts here. | +| **#183** Divergent relationships | HIGH | **CRITICAL** | Nigel | Inverted emotional landscape per character. Non-negotiable for two-reality proof. | +| **#162** Storyteller module activation | LOW | **MEDIUM** | Ozzie, Gestalt | Even a simple timer gives the 30-min arc shape. Without it, daily life has no crescendo. | + +--- + +## 7. Testability Decisions + +### Eight Final Decisions for Ticket #214 + +Confirmed by Tyre and Hoshe after two rounds of analysis. Changes from Round 1 marked. + +#### Decision 1: Rust test organization = Hybrid (UNCHANGED) + +- `#[cfg(test)]` for unit tests inside modules (algorithm internals, pure functions) +- `tests/` directory for integration tests (full tick loop, multi-system interaction) +- Both run via `cargo nextest run` +- No dissent. + +#### Decision 2: Godot test framework = gdUnit4 (CHANGED from GUT) + +- Install gdUnit4 as addon in client project +- Headless execution via `godot --headless` + `GdUnitCmdTool` +- JSON output format for agent consumption +- `GdUnitSceneRunner` for scene lifecycle tests (dialogue UI, fog rendering) + +**Changed because:** Hoshe's comparison demonstrated gdUnit4's advantages for agent-driven development: native JSON output, stable headless support via `GdUnitCmdTool`, `GdUnitSceneRunner` for scene tests, and organizational maintenance (godot-gdunit-labs vs single maintainer). Tyre acknowledged: "I was wrong in Round 1, and Hoshe's argument is better." + +#### Decision 3: IPC testing = Three-layer architecture (EXTENDED from "real IPC") + +| Layer | Scope | Speed | Frequency | +|-------|-------|-------|-----------| +| Layer 1 — Fixture-based | Serialization roundtrip, cross-language verification | < 1 second | Every edit cycle | +| Layer 2 — Protocol state machine | Mock subprocess, handshake/error/recovery | < 10 seconds | Every PR | +| Layer 3 — Real integration | Actual simulation binary, real protocol | < 60 seconds | Daily / pre-merge | + +**Extended because:** Hoshe's three-layer approach adds fast feedback for serialization changes and protocol state machine testing without contradicting Tyre's "real IPC for integration truth" position. The layers are complementary. + +#### Decision 4: Production code constraints + CauseChain endorsed (UNCHANGED + EXTENDED) + +Five constraints: +1. No conditional compilation that changes production behavior +2. No `pub` visibility escalation solely for tests +3. No test-specific parameters on production functions +4. Public API is the test surface +5. ECS World setup replaces mock injection + +**CauseChain endorsed as production component, not test pollution.** Serves four production purposes: (1) monologue integration ("I saw..." vs "I overheard..."), (2) knowledge journal provenance, (3) debugging/causality tracing, (4) success criteria validation (D-027 criterion 4). Every design agent independently flagged the need CauseChain addresses. Implementation: `CauseChain` component with `Vec`, each step containing `Cause` enum variant (VisualObservation, AudioObservation, DialogueReveal, InferredFromPattern, InstitutionalAccess, StartingKnowledge, ScriptedReveal). + +#### Decision 5: Test runner tooling (UNCHANGED) + +- `cargo-nextest` for Rust (parallel execution, isolated processes, structured output) +- gdUnit4 for Godot (JSON output, scene runner, stable headless) +- Bash wrapper scripts in `test/` directory, whitelistable for Claude Code agents +- Each script: exit code 0/non-zero, structured stdout, accepts filter arguments, no interactive input + +#### Decision 6: Test output format = JSON summary (MERGED) + +All test runners produce a consistent JSON schema: +```json +{ + "suite": "simulation::perception", + "runner": "cargo-nextest", + "duration_ms": 247, + "total": 15, + "passed": 14, + "failed": 1, + "failures": [{ "test": "...", "file": "...", "line": 142, "message": "..." }] +} +``` + +Rust: `cargo-nextest` output normalized to JSON by wrapper script. Godot: gdUnit4 native JSON. JUnit XML as secondary format for future CI integration. + +#### Decision 7: Deterministic replay promotion (NEW from Hoshe) + +- **Promote #201 (Deterministic replay system) from HIGH to CRITICAL** +- Simulation must consume time, randomness, and player input exclusively through injectable resources: `SimulationTime`, `SimRng` (seeded from world seed), `InputQueue` +- No `std::time::Instant`, no `rand::thread_rng()` +- This is a production architecture requirement (D-010 principle 4), not test infrastructure +- Without determinism: sync tests (#211), divergence tests (#197), and cross-seed validation (#178) are impossible + +#### Decision 8: Test priority alignment with hard blockers (NEW from design team) + +Three-phase test priority: + +| Phase | Sprint | Focus | +|-------|--------|-------| +| Phase 1: Foundation | Sprint 1-2 | Test infra setup, first tests alongside collision/pathfinding/time | +| Phase 2: System integration | Sprint 3-4 | Monologue pipeline integration test (highest-value), information boundary negative tests | +| Phase 3: Content validation | Sprint 5+ | CauseChain verification, divergent snapshot tests, content regression | + +**Key insight (Tyre):** The monologue pipeline integration test is the single highest-value test in the project — it exercises perception, time, routines, information boundaries, and monologue generation in one chain. + +--- + +## 8. Narrative Requirements + +### Paula + Gore: "Perspective and Arc" Authoring Specification + +Paula and Gore independently converged on the same diagnosis from different angles. Paula identified "interpretive asymmetry" (characters don't just know different things — they THINK differently). Gore identified "identity shapes reality" (the thesis). Their merged output is a content authoring specification. + +**Document title:** "Perspective and Arc — v0.1 Authoring Specification" +**Assigned to:** Gore (thematic framing), Paula (narrative structure), Mellanie (authoring execution), Miri (setting grounding) +**Estimated length:** ~12-15 pages + +**Contents:** +1. **Thesis statement** — Falsifiable claim: "A player who completes both playthroughs should report that they felt like they played two different games set in the same place." +2. **Shared reality map** — Every NPC/location both characters encounter, with what each character SEES through their lens. +3. **Monologue pair templates** — 10-15 paired monologue examples showing same observation, different identity, different interpretation. +4. **Recontextualization moments** — 2-3 moments designed for second-playthrough vertigo. Authored backward from the reveal. +5. **Emotional registers per character** — Not voice guides but emotional posture guides (smuggler: managing anxiety beneath casual competence; detective: controlled professional attention). +6. **The ethical layer** — How both characters' monologues acknowledge the moral dimension of watching. Not preachy — texture. +7. **The quiet life** — Guidance for the 30% flat and 50% mundane NPCs. "Write these NPCs as people, not as noise." + +### Three Must-Deliver Narrative Moments (Paula) + +| Moment | Timing | Emotional Arc | Systems Required | Minimum Conditions | +|--------|--------|---------------|------------------|--------------------| +| **Recognition Divide** | Minutes 0-5 | Curiosity -> "my character sees differently than I expected" | Info boundaries + monologue + character builds | 5 shared NPCs with dual monologue sets | +| **Absence That Speaks** | Minutes 10-20 | Familiarity -> disruption -> anxiety -> "something's wrong" | Routines + absence detection + fog + monologue | 2 NPCs with deviation events + absence monologue | +| **Cost of Knowing** | Minutes 20-30 | Attachment -> discovery -> moral weight -> "what do I do?" | All social systems + information gain + monologue | 1 NPC per character with positive rapport + incriminating discovery | + +**Arc across all three:** Innocence -> awareness -> moral complexity. Plays out in 30 minutes. Plays differently per character because each starts from different "innocence." + +### Gore's Three Load-Bearing Moments + +1. **The Interpretive Split** — Same NPC, same behavior, two completely different monologue interpretations. The thesis in its purest form. +2. **The Recontextualization** — Second-playthrough vertigo when the player sees their first playthrough's reality was constructed. Most powerful emotional payload. +3. **The Quiet Life Moment** — An unentangled NPC who is interesting to observe on their own terms. Proves the thesis extends beyond intrigue. + +### Minimum Narrative Investment + +~80-100 critical monologue lines (dual-interpretation + absence + arc progression) plus the authoring specification. Approximately 5-8% of total v0.1 content work, but load-bearing for 100% of the thesis proof. + +### Role-Archetype Authoring (Paula + Nigel) + +Paula resolved the tension between narrative depth and seed variation: author for ROLES, not individuals. "The colleague who's in too deep" is a role archetype with monologue templates and arc structures. Each seed fills the role with a different NPC. Trait modifiers (#173) reshape delivery per NPC. + +**Design constraint (Gore):** Seed variation changes the world's CONTENT (who, what, when). Character identity changes the world's MEANING (why, how, what-it-feels-like). These axes must stay distinct. If the smuggler in seed B feels like a different person than the smuggler in seed A, the thesis collapses. + +--- + +## 9. Replayability Assessment + +### Nigel's Final Replay Ceiling: 10-12 Playthroughs + +| Scenario | Estimated Playthroughs | Change from Round 1 | +|----------|----------------------|---------------------| +| Current plan (no changes) | 2 | -- | +| + #178 promoted to HIGH | 4-5 | -- | +| + Observation pipeline + deviation detection | 6-8 | NEW | +| + Triangle escalation + social propagation | 7-9 | NEW | +| + Interpretive framing + character objectives | 8-10 | NEW | +| + Opening hooks (seed-aware) + tell variation | 9-12 | NEW | +| **ALL proposed changes integrated** | **10-12** | Up from 6-8 in Round 1 | + +**Key insight:** The experience layer IS the replayability layer. Gestalt and Ozzie's observation pipeline makes seed variation VISIBLE to the player. Without it, seeds differ under the hood but the player doesn't notice. With it, every structural variation becomes a felt experience. + +**The math:** 2 characters x 3-4 meaningfully different seed configurations x 1.5-2x experiential variation from observation pipeline + deviation detection = 9-16 theoretical, constrained to 10-12 by content depletion (dialogue lines, NPC personality variety). + +### Replayability Architecture = Game Architecture + +Every system that makes the first playthrough good ALSO makes subsequent playthroughs different — IF it's seed-aware and feeds into the observation pipeline: + +| Agent | Designed For | Replayability Contribution | +|-------|-------------|---------------------------| +| Gestalt | Player verbs / experience layer | Observation pipeline makes seed variation visible | +| Ozzie | Wow moments / emotional delivery | Deviation detection makes fog replayable | +| Paula | Narrative connective tissue | Triangle escalation timing varies per seed | +| Gore | Thematic unity | Character-as-reality framing makes switching characters feel like switching genres | +| Tyre | Technical foundations | Deterministic simulation makes seed variation reliable | +| Hoshe | Testability | Automated cross-seed comparison validates replayability | +| Nigel | Seed variation | The structural floor all other systems multiply against | + +### Nigel's Extended Thesis + +"Who you are determines what is real. And what is real changes every time." + +- Character variation = DEPTH (fundamentally different experiences from the same events) +- Seed variation = BREADTH (can't metagame, can't solve, can't predict) +- Together: every playthrough is a genuinely new experience + +--- + +## 10. Open Question Resolutions + +### Q-009: Time System — Proposal (AWAITING CONFIRMATION) + +Tyre and Gestalt converged on a time system proposal. Both support the same parameters: + +| Parameter | Value | Rationale | +|-----------|-------|-----------| +| Tick rate | 10 tps | Already decided (D-026) | +| Tick-to-game-time | 10 ticks = 1 game-minute | 30-min play session = ~18 game-hours. Full "day" in one session. | +| Day phases | Morning (6-12), Afternoon (12-18), Evening (18-24), Night (0-6) | 4 phases drive routine transitions | +| Time display | In-universe insert clock | Diegetic, always visible | +| Pause | Yes (single-player) | Simulation freezes, UI responsive | +| Time-skip | Deferred to WAIT verb (medium priority) | Nice-to-have, not blocker | + +**Status:** Workshop consensus. Requires team leader confirmation to close Q-009. + +### Other Open Questions + +- **Q-002** (v0.1 mechanics scope): Significantly advanced by this workshop. The 33 new tickets + priority adjustments define the remaining scope. +- **Q-010** (Storyteller AI design): Partially addressed — contamination activation mechanic (H-11) is a simplified v0.1 storyteller. Full design deferred. +- **Q-011** (Character selection): Partially addressed — smuggler + detective confirmed (D-027), character builds (#179-183) define the two playable characters. + +--- + +## 11. Key Convergences + +### Independent Discovery of the Same Gaps + +The workshop's most striking outcome was the degree of independent convergence. Agents working on different tracks from different domain perspectives repeatedly identified the same missing systems: + +| Gap | Agents Who Independently Identified It | Name Each Used | +|-----|---------------------------------------|----------------| +| **Observation event pipeline** | Ozzie ("observation event pipeline"), Gestalt ("player interaction framework"), Paula ("knowledge-aware monologue integration"), Gore ("the meaning isn't wired in") | 4 agents, 4 names, 1 system | +| **Routine deviation detection** | Ozzie ("routine deviation detection"), Paula ("absence detection"), Gestalt ("NPC off-routine behavior"), Nigel ("what makes fog replayable") | 4 agents, 4 angles, 1 system | +| **Monologue as MVP** | Ozzie ("the monologue IS the game"), Paula ("the MVP of narrative delivery"), Gore ("the system that constructs reality"), Gestalt ("where identity shapes perception") | Universal agreement on monologue as the critical integration point | +| **#178 promotion** | Nigel (replayability engine), Gestalt (anti-metagaming), Ozzie (replay sustainer), Paula (role-archetype compatibility) | 4 agents, all recommending LOW -> HIGH | +| **#103 + #105 promotion** | Paula (narrative), Gestalt (systems), Ozzie (emotional delivery) | 3 agents independently, from different domains | +| **Experience layer gap** | Gestalt (named it), Ozzie (diagnosed it), Paula (specified the narrative tissue), Gore (specified the meaning) | Universal pattern recognition | + +### The Unified Observation System + +Gestalt's Round 2 synthesis merged Ozzie's pipeline + Gestalt's verbs + Paula's absence detection into a three-layer system: + +``` +Layer 1: PERCEPTION (existing tickets, complete) + #110-113 (vision), #124-128 (sound), #115 (NPC vision) + -> Raw sensory data + +Layer 2: INTERPRETATION (the missing spine) + Character knowledge + perceived data -> Observation Events + Includes: routine deviation, absence detection, social anomaly, + new information, contradiction + -> Feeds monologue (#119-122) as trigger events + +Layer 3: ACTION (the missing player agency) + FOLLOW, EXAMINE, INTERACT + -> Each changes information flow +``` + +**The observation event generator** (C-4) sits at Layer 2 and is the mechanical expression of Gore's thesis: it queries character identity to determine what the character notices, producing different observation events for different characters witnessing the same NPC behavior. + +--- + +## 12. Dissent and Unresolved Issues + +### Resolved Disagreements + +**GUT vs gdUnit4:** Tyre recommended GUT in Round 1; Hoshe recommended gdUnit4. Resolved in Round 2 — Tyre changed position after Hoshe's comparison demonstrated gdUnit4's advantages for agent-driven development (JSON output, stable headless, organizational maintenance). No remaining dissent. + +**Arcs vs Conditions (Paula vs Gore):** Paula thinks in designed narrative arcs (safety -> pressure -> crisis -> choice). Gore thinks in systemic conditions that produce emergent arcs ("design the pressure, not the plot"). This is a real design tension, not a semantic one. **Resolution:** "Design the pressure, not the plot." Monologue tone shifts driven by tracked discovery count, relationship state, and elapsed time — not by scripted triggers. The storyteller modulates pacing, but player actions determine when phase transitions occur. Both agents accept this framing. + +### Unresolved Issues + +**Q-009 confirmation:** Time system proposal has full workshop consensus but requires team leader sign-off to close formally. + +**Priority conflict — #162 (Storyteller):** Ozzie wants HIGH promotion; Gestalt supports HIGH; Nigel defers to MEDIUM. Workshop consensus settled on MEDIUM as the minimum, with the design team acknowledging even a timer-based trigger is needed. + +**Scope of authoring specification:** The Perspective and Arc document is 12-15 pages. Whether this is authored before or alongside implementation is not settled. + +**Tyre's new technical tickets (16 total):** These overlap with but are not identical to Gestalt's consolidated 33. Reconciliation of the two lists into a single ticket backlog for Si to process is a follow-up action. + +**Performance benchmarks (#204):** Deferred beyond #214. No baselines defined yet (tick budget, entity count targets, serialization throughput). Not urgent for v0.1 with ~25 NPCs. + +--- + +## Decisions Produced + +This round produced the following confirmed decisions: + +- **D-030:** Testability architecture decisions (8 sub-decisions for #214) — see Section 7 +- **Q-009 time system proposal** awaiting team leader confirmation + +## Source Documents + +All workshop files are located at `docs/workshops/`: + +| File | Agent | Round | +|------|-------|-------| +| `v01-gap-analysis-workshop-brief.md` | Team Leader | Brief | +| `round1-gestalt.md` | Gestalt | Round 1 | +| `round1-ozzie.md` | Ozzie | Round 1 | +| `round1-paula.md` | Paula | Round 1 | +| `round1-gore.md` | Gore | Round 1 | +| `round1-nigel.md` | Nigel | Round 1 | +| `round1-tyre.md` | Tyre | Round 1 | +| `round1-hoshe.md` | Hoshe | Round 1 | +| `round2-gestalt.md` | Gestalt | Round 2 | +| `round2-ozzie.md` | Ozzie | Round 2 | +| `round2-paula.md` | Paula | Round 2 | +| `round2-gore.md` | Gore | Round 2 | +| `round2-nigel.md` | Nigel | Round 2 | +| `round2-tyre.md` | Tyre | Round 2 | + +--- + +*Documented by Qatux. Round 18 of The Settled Reach design process.* diff --git a/docs/workshops/README.md b/docs/workshops/README.md new file mode 100644 index 000000000..b69600d35 --- /dev/null +++ b/docs/workshops/README.md @@ -0,0 +1,21 @@ +# Workshops + +Each workshop gets its own directory containing the brief and all output files. + +## Convention + +``` +docs/workshops/ + {workshop-name}/ + {workshop-name}-workshop-brief.md # The original brief + round1-{agent}.md # Round 1 per-agent analyses + round2-{agent}.md # Round 2 per-agent syntheses + si-ticket-changes.md # Ticket changes applied (if any) +``` + +## Workshops + +| Workshop | Round | Status | +|----------|-------|--------| +| [Content Architecture](content-architecture/) | 17 | Complete | +| [v0.1 Gap Analysis](v01-gap-analysis/) | 18 | Complete | diff --git a/docs/workshops/content-architecture-workshop-brief.md b/docs/workshops/content-architecture/content-architecture-workshop-brief.md similarity index 100% rename from docs/workshops/content-architecture-workshop-brief.md rename to docs/workshops/content-architecture/content-architecture-workshop-brief.md diff --git a/docs/workshops/v01-gap-analysis/round1-gestalt.md b/docs/workshops/v01-gap-analysis/round1-gestalt.md new file mode 100644 index 000000000..ae4c52b4a --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round1-gestalt.md @@ -0,0 +1,463 @@ +# Round 1 Workshop Response: Gestalt (Systems Design) + +**Agent:** Gestalt (Systems Design & Fun Factor) +**Date:** 2026-02-11 +**Scope:** Tracks 1, 2, 3 + +--- + +## Track 1: Strength of Concept Proof + +*Let me break down what each claim actually means mechanically, and whether the tickets deliver it.* + +### Claim 1: Asymmetric Information is the Core Mechanic + +**Rating: INFRASTRUCTURE STRONG, EXPERIENCE GAP** +**Risk: MEDIUM-HIGH** + +| Ticket(s) | What they deliver | What's missing | +|-----------|-------------------|----------------| +| #138-142 (info boundaries) | Data layer: who knows what, entity visibility filtering, access control | How the player EXPERIENCES asymmetry | +| #182-183 (divergent knowledge/relationships) | Starting state differences between smuggler and detective | Ongoing divergence during play | +| #119-122 (monologue) | Character-specific interpretation of observations | Integration: monologue triggered BY information boundary differences | +| #168-174 (dialogue) | Access-tier filtered conversations | Integration: same NPC giving demonstrably different info to different characters | + +**The gap:** The information boundary system (#138-142) is the ENGINE. The monologue (#119-122) and dialogue (#168-174) are the INTERFACE. But there's no ticket for the INTEGRATION layer that makes asymmetry *experienceable*. Specifically: + +- **No "asymmetry moment" authoring ticket.** Who writes the content that makes the smuggler's internal monologue say "the usual cargo run" while the detective's says "those shipping manifests don't match"? This falls somewhere between Mellanie's content packs (#190-192) and the monologue line pool (#120), but the specific design of *character-divergent reactions to the same observations* isn't called out. +- **No ticket for the player discovering they were wrong.** Asymmetric information is most powerful when the player realizes their character's view was incomplete or wrong. How does this realization surface mechanically? Monologue? Dialogue? Environmental discovery? + +**Minimum bar for v0.1:** The player must, at least once per playthrough, encounter a situation where they later realize "oh, *that's* what was really happening" — and the realization comes from systems, not a scripted reveal. + +### Claim 2: Fog of Perception Creates Tension + +**Rating: SOLID** +**Risk: LOW-MEDIUM** + +| Ticket(s) | What they deliver | What's missing | +|-----------|-------------------|----------------| +| #110-113 (fog pipeline) | Shadowcasting, vision cone, observer query, fog rendering — all critical priority | Nothing missing in the pipeline itself | +| #124-128 (sound model) | Sound events through fog, directional indicators | Close-range (#125) is high, medium-range (#126) is medium — this ordering is correct | +| #115 (NPC vision) | NPCs use the same system | Solid | + +**The tension question:** Fog creates tension only when there's something to be tense ABOUT. A fog system over a static, predictable world is just visual clutter. Tension requires: + +1. NPCs occasionally being where you don't expect them (#88 routines are predictable by design) +2. Sounds from fog-edge creating decision moments ("investigate or ignore?") +3. The possibility that what you can't see CAN hurt you or surprise you + +**Gap:** NPC off-routine behavior. The routine system (#88, #101) makes NPCs predictable — which is great for investigation ("they always go to the back room at 3pm"). But for fog to create tension, NPCs need to occasionally deviate. The smuggling ring NPCs (#186) should have secret activities that break their public routine. This is implied but not explicitly ticketed as a behavior system. + +**Minimum bar for v0.1:** At least one moment per playthrough where the player hears something through fog and has to decide whether to investigate. This is emergent if the sound system (#124-125) and NPC routines (#88, #101) work together — but it's worth validating that the content creates these moments. + +### Claim 3: NPCs Feel Alive Without Player Attention + +**Rating: STRONGEST CLAIM** +**Risk: LOW** + +| Ticket(s) | What they deliver | What's missing | +|-----------|-------------------|----------------| +| #88 (daily routines) | NPCs have schedules — critical | Nothing in isolation | +| #93-99 (simulation tiers) | Full tier pipeline from active to state-saved | Comprehensive | +| #101 (routine execution) | NPCs actually follow routines | Solid | +| #102 (mood), #103 (relationship dynamics) | NPCs' internal state changes over time | Both medium priority — should at least one be promoted? | + +**This is our best-covered claim.** The tier system (D-026) ensures NPCs are simulated even off-screen. The routine system (#88) gives them predictable daily lives. The relationship dynamics (#103) mean things change while you're away. + +**Gap — discovery of off-screen life:** The player needs to NOTICE that NPCs lived without them. Two mechanisms: +1. **Dialogue references to off-screen events** — "Did you hear about the argument at the bar last night?" This requires content in the content packs (#190-192) and the dialogue system to surface it. Partially covered by Layer 4: Unprompted disclosure (#172), but #172 is medium priority. +2. **Environmental state changes** — not ticketed at all. If the bar looks identical at 2am and 2pm, the world feels static even if NPC state changed. Even simple things (lights on/off, tables occupied/empty, items moved) would sell this. + +**Minimum bar for v0.1:** When the player returns to a location they've visited before, at least one NPC should mention something that happened while the player was away, and at least one visible detail should have changed. + +### Claim 4: Observation is a Mechanic, Not a Cutscene + +**Rating: PIPELINE STRONG, PLAYER VERBS MISSING** +**Risk: HIGH** + +| Ticket(s) | What they deliver | What's missing | +|-----------|-------------------|----------------| +| #110-113 (vision) | What the player can see | Passive: info flows TO player | +| #124-128 (sound) | What the player can hear | Passive | +| #119-122 (monologue) | Character interprets observations | Passive | +| #115 (NPC vision) | NPCs can see the player | Reactive: NPCs respond to player presence | + +**Critical gap: OBSERVATION VERBS.** The perception pipeline delivers information to the player. But "observation as a mechanic" means the player must DO something active: + +| Missing verb | What it means | Why it matters | +|--------------|---------------|----------------| +| **FOLLOW** | Maintain distance behind an NPC, track their movement | Core investigation mechanic. The observe->follow->discover sequence (D-027 criterion 4) literally requires this | +| **WAIT/STAKE OUT** | Stay in one location and let time pass while watching | Classic detective mechanic. Without it, the player can only observe in real-time | +| **EXAMINE** | Look closely at an object, container, terminal, document | Without this, the environment is wallpaper | +| **EAVESDROP** | Position yourself to overhear a conversation in progress | The sound model enables this spatially, but the player needs to know they're eavesdropping | + +The D-027 criterion says "observe -> notice -> follow -> discover must emerge from systems, not scripts." But FOLLOW doesn't have a ticket. Neither does any active observation verb. The perception pipeline is the sensory layer. The player agency layer for observation is missing. + +**Minimum bar for v0.1:** Player can follow an NPC (the game tracks that you're following and adjusts monologue accordingly). Player can examine key objects. These two verbs plus the existing perception pipeline would be sufficient to prove the claim. + +### Claim 5: Same World, Different Story + +**Rating: SETUP STRONG, GAMEPLAY DIVERGENCE UNCLEAR** +**Risk: MEDIUM-HIGH** + +| Ticket(s) | What they deliver | What's missing | +|-----------|-------------------|----------------| +| #179-183 (character builds) | Two distinct characters with different knowledge/relationships | Character GOALS/MOTIVATIONS | +| #196-199 (success criteria validation) | Testing framework | These are tests, not content | +| #169 (access tier filtering) | Different dialogue per character | Correct mechanism | +| #119-122 (monologue) | Different internal voice | Correct mechanism | + +**The gap: what is the player DOING?** Two characters seeing the world differently is necessary but not sufficient. They need to be DOING different things. + +- **Smuggler:** what are their objectives? Maintain their cover? Complete a drop? Manage their contacts? There's a smuggling ring template (#186) but no ticket for "smuggler gameplay objectives." +- **Detective:** what are they investigating? Who assigned the case? What's their mandate? The detective has "authority access, analytical" — but what is the investigation ABOUT? + +Without character-specific goals that drive different ACTIONS, the two playthroughs will feel like "same walking simulator, different flavor text." The characters need mechanical goals — even implicit ones driven by their starting state — that push them to different parts of the game space, different NPCs, different decisions. + +**Minimum bar for v0.1:** The smuggler and detective should have at least one distinct mechanical objective that sends them to different places and creates different social dynamics. Not a quest log — a systemic pressure. The smuggler needs to maintain relationships with ring members (relationships erode if ignored). The detective needs to gather evidence (knowledge state builds toward a threshold). These feel like system-level features, not content. + +### Claim 6: Social Triangles Create Emergent Drama + +**Rating: GENERATION COVERED, ACTIVATION NOT** +**Risk: HIGH** + +| Ticket(s) | What they deliver | What's missing | +|-----------|-------------------|----------------| +| #106-109 (triangle generation) | Schema, intra-template, cross-template, validation | Triangle DEFINITION — potential energy | +| #175-176 (entanglement ratio, NPC pool) | Population balance for triangles | Correct population math | +| #103 (relationship dynamics) | Relationships change over time | Closest to activation, but medium priority | +| #105 (tolerance threshold triggers) | NPCs snap when pushed too far | One activation mechanism, medium priority | + +**Critical gap: triangle RESOLUTION mechanics.** A triangle is potential energy: NPC A wants X, NPC B wants Y, NPC C is caught between. But what makes the drama HAPPEN? The triangle needs to ACTIVATE — produce observable events that the player can witness or discover. + +Triangle activation requires: +1. **Triggering conditions** — when does tension in a triangle boil over? Tolerance (#105) is one mechanism, but it's medium priority. +2. **NPC confrontation behavior** — NPC A confronts NPC C about NPC B. This is an NPC behavior that needs to be simulated, not just tracked. +3. **Observable events** — the confrontation needs to happen in game-space where the player can see/hear it. This ties to routine deviation (NPC breaks routine to confront someone) and sound events (raised voices audible through fog). +4. **Consequences** — after a triangle event, relationship states change, routines adjust, secrets potentially spill. This feeds back into the social system. + +Without activation mechanics, triangles are authored backstory, not emergent drama. The player will learn about triangle tensions through dialogue, but never WITNESS them playing out in the simulation. + +**Minimum bar for v0.1:** At least one triangle should activate during a 30-minute playthrough. The player should be able to witness (or hear, or discover evidence of) an NPC confrontation that arose from triangle tensions. This means #103 and #105 should probably be promoted from medium to high priority. + +### Concept Proof Scorecard Summary + +| Claim | Infrastructure | Experience | Overall Risk | Key Gap | +|-------|---------------|------------|-------------|---------| +| Asymmetric information | Strong | Gap | MEDIUM-HIGH | Character-divergent content integration | +| Fog of perception | Strong | Adequate | LOW-MEDIUM | NPC off-routine behavior for tension | +| NPCs alive off-screen | Strong | Gap | LOW | Discovery mechanisms for off-screen life | +| Observation as mechanic | Strong | Missing | HIGH | Player observation verbs (follow, examine) | +| Same world, different story | Setup done | Missing | MEDIUM-HIGH | Character mechanical objectives | +| Social triangles | Schema done | Missing | HIGH | Triangle activation/resolution mechanics | + +**Overall assessment:** Our INFRASTRUCTURE is strong. Our SYSTEMS are well-designed. The gap is consistently in the **EXPERIENCE LAYER** — the place where systems produce moments the player actually encounters. This is the classic systems design trap: building the engine without building the verbs and events that make the engine produce gameplay. + +--- + +## Track 2: Fun & Wow Factor + +### What's the Single Most Exciting Thing in 30 Minutes? + +The smuggler watches their coworker — someone they've been working with, someone they greet every morning — walk into the back room at the wrong time. The monologue fires: "That's the third time this week. Something's off." The player follows. They overhear a conversation through the wall (medium-range sound). They realize: their coworker is talking to someone the smuggler knows is from the enforcement side. Their trusted colleague is an informant. + +Or from the detective side: they interview a bar regular. Friendly, cooperative, nothing to hide. But later, staking out the bar at night, they see that same regular meet with someone in the alley. The monologue: "Interesting company for a shipping clerk." The detective has a choice: confront now or keep watching. + +**These moments are the game.** And they emerge from systems interacting: routine + secret + perception + monologue + NPC relationships. That's the good news — our systems are designed to produce these moments. + +**The bad news:** I can describe these moments, but I can't point to a ticket that guarantees they happen. They're emergent. They depend on: +- NPC secret behavior being observable (#88 + something not yet ticketed) +- The player being in the right place (spatial design #153-155) +- The monologue firing the right line (#119-120 + content #190-192) +- The player having enough context to recognize the anomaly (prior dialogue + information state) + +### Are We Front-Loading the Fun? + +**CONCERN: No.** The first 5 minutes are likely to be: +1. Character spawns in the station district +2. Player sees their immediate surroundings (fog reveals area) +3. Player can walk around +4. Player... does what? + +There's no opening hook. No "you have a message on your insert" moment. No "your shift starts in 10 minutes" prompt. No immediate pull. + +**Missing ticket: opening sequence/hook for each character.** Not a cutscene — a systemic hook. The smuggler's insert buzzes with a message from their contact: "Shipment delayed. Meet me at the usual place." The detective's case file updates: "New lead in sector 7." These are information events that use existing systems (insert/minimap #148-149, monologue #119-122) but they need to be designed and authored. + +Without an opening hook, we're asking players to explore a station district with no goal and discover emergent gameplay through wandering. That's a recipe for confusion, not excitement. + +### Which Tickets Are Wow vs Infrastructure? + +| Category | Tickets | Count | +|----------|---------|-------| +| Pure infrastructure | #65-69, #70-74, #75-80, #81-85 (engine), #218-232 (tasks), #93-100 (tiers), #143-147 (chunks), #200-217 (testing) | ~80 | +| Foundation that enables wow | #86-92 (NPC data), #110-113 (fog), #138-142 (info boundaries), #129-133 (renderer) | ~25 | +| Wow-adjacent (systems that produce moments) | #88 (routines), #101 (routine execution), #106-109 (triangles), #119-122 (monologue), #124-128 (sound), #168-174 (dialogue) | ~25 | +| Direct wow (player-facing payoff) | #179-183 (character builds), #182-183 (divergent experience), #184-188 (station content), #189-194 (authored content) | ~15 | +| Validation/testing | #195-199, #200-217 | ~20 | + +**The ratio is infrastructure-heavy**, which is expected for a foundation build. But the "direct wow" tickets are almost entirely content authoring (#189-194) and character setup (#179-183). There are very few MECHANICS tickets in the wow category. This confirms the Track 1 finding: the experience layer is thin. + +### Is There a 2-Minute Demo Moment? + +**Best candidate: the split-screen concept proof.** + +Show the same 60 seconds of gameplay from both characters. The smuggler walks through the logistics hub. Monologue: casual, familiar, routine. They greet a coworker. Normal day. The detective walks through the same hub. Monologue: analytical, suspicious. Same coworker, different greeting — the detective gets the polite-but-guarded version. The detective's insert flags the coworker's cargo manifest as anomalous. + +Same world. Different experience. 60 seconds. Core concept proven. + +**Requirements:** #179-181 (characters), #119-122 (monologue), #138-140 (info boundaries), #168-169 (dialogue access tiers), #129-131 (renderer), #113 (fog). All are in the plan. This is achievable. + +**Promote this as a milestone target.** A side-by-side video of this demo would be enormously powerful for validating the concept. + +### Where's the First "Aha" Moment? + +The "aha" moment is: "Wait, this NPC knows something they're not telling me." + +This requires: +1. The player talks to NPC. NPC is friendly/normal. (#168-169 dialogue) +2. Later, the player observes NPC doing something contradictory. (#88 routine, #110-112 perception) +3. Monologue fires: interpretive commentary linking the contradiction. (#119-120) +4. The player realizes: that first conversation was a performance. + +**Timeline:** This can't happen in the first 5 minutes. The player needs to establish a baseline expectation before it can be subverted. Earliest realistic "aha": ~10-15 minutes in, after the player has talked to several NPCs and gotten a feel for "normal." + +**Risk:** If it takes longer than 15-20 minutes for ANY observation-based discovery to occur, the player will think the game is boring. The content packs (#190-192) need to ensure that at least one observable secret is available early. + +### Is Daily Life Interesting Enough for 30 Minutes? + +**Honest answer: uncertain.** + +The 30/50/20 split (D-029) means: +- ~6-10 flat NPCs (routine + greeting only) — these are wallpaper +- ~10-15 mundane triangle NPCs (disputes, rivalries, tensions) — these ARE the daily life game +- ~4-6 entangled NPCs (connected to smuggling ring) — these are the intrigue layer + +For 30 minutes of daily life to be interesting, the **mundane triangles must be engaging.** A workplace rivalry. A bar regular who's cheating on their partner. A neighbor dispute about noise. These are small-stakes but relatable dramas that the player discovers through observation and conversation. + +**Content volume concern:** Each template gets ~165-210 authored lines, expanded 4x. With 3 templates, that's ~2,000-2,500 total lines. If the player talks to 20-30 NPCs in 30 minutes, averaging 4-5 lines per conversation, that's ~100-150 lines consumed per playthrough. Budget seems adequate — but variety matters. If 3 NPCs give the same style of greeting, it feels repetitive even with different words. + +**Systemic concern:** Daily life needs ACTIVITIES, not just conversations. What does the player DO between conversations? Walk around and watch NPCs? That's passive. The player needs micro-decisions: where to go next, who to talk to, what to examine, whether to follow someone. These are the observation verbs I flagged in Track 1 — without them, daily life is a walking simulator with dialogue. + +### Missing Wow Moments (Systems Design Perspective) + +1. **The betrayal discovery.** You trusted an NPC. They were friendly, helpful, consistent. Then you discover they've been reporting your movements. Not through a scripted reveal — through observation and deduction. *Requires: NPC double-agent behavior (secret routine) + player observation mechanics + monologue interpretation.* + +2. **The overheard conversation.** You're walking past a wall. You hear voices through it — two NPCs talking about someone. It's you. *Requires: sound propagation (#124-128) + NPC-to-NPC conversation system (NOT TICKETED) + monologue interpretation.* + +3. **The routine break.** An NPC who's been on the same schedule for days suddenly deviates. Where are they going? Why now? *Requires: NPC off-routine behavior (NOT TICKETED) + perception system + monologue flagging the deviation.* + +4. **The wrong place at the wrong time.** You walk into a room and interrupt something. Two NPCs jump apart, conversation stops. *Requires: NPC reaction to player presence (#115 NPC vision) + NPC behavior state changes (NOT TICKETED).* + +--- + +## Track 3: Things We May Have Forgotten (Systems Design) + +### Critical Missing Systems + +#### 1. Player Interaction System (NO TICKETS) + +**Severity: CRITICAL BLOCKER** + +The player can move, look, and listen. But there's no ticket for the basic interaction verb set: + +| Verb | Description | v0.1 necessity | +|------|-------------|----------------| +| INTERACT | General-purpose "use" action on entities/objects | Critical — without this, the world is untouchable | +| EXAMINE | Look closely at something for details | High — feeds investigation mechanic | +| FOLLOW | Track an NPC's movement | High — D-027 criterion 4 literally requires this | +| TALK | Initiate dialogue with NPC | Covered by #168-174 | +| WAIT | Let time pass while staying in place | Medium — enables stakeout mechanic | +| USE DOOR | Open/close doors | Medium — basic spatial interaction | +| PICK UP | Take items from environment | Low for v0.1 — can defer | + +The dialogue system (#168-174) covers TALK. Everything else is unticketted. At minimum, INTERACT and EXAMINE need tickets. FOLLOW is required by D-027's success criteria. + +**Proposed new tickets (3-4 stories):** +- Player interaction system — entity interaction framework (critical) +- Follow mechanic — track NPC movement with distance/detection (high) +- Examine mechanic — inspect objects/entities for detail info (high) +- Wait/time-skip mechanic — advance time while observing (medium) + +#### 2. Character Objectives / Motivation System (NO TICKETS) + +**Severity: HIGH** + +What is the player TRYING TO DO? The smuggler and detective have different starting states, but no mechanical goals. + +For emergent gameplay, goals don't need to be explicit quest objectives. They can be systemic pressures: +- **Smuggler:** your contact expects you to show up for drops. Missing a drop damages your relationship (and your cover). Your tolerance threshold for risk slowly climbs as the ring gets more aggressive. Daily life = balancing normal work + criminal obligations. +- **Detective:** your case file contains leads that decay over time. The longer you wait to follow up, the less useful they become. Your superior expects progress reports. Daily life = balancing investigation + institutional obligations. + +These are not quest systems — they're relationship/information pressures that create emergent deadlines. They use existing systems (relationships #87, information #89, tolerance #105) but need a character-specific goal layer. + +**Proposed: character goal framework story (high priority).** Not a quest log — a pressure system that uses existing NPC axes to create character-specific pulls. + +#### 3. NPC-to-NPC Conversation System (NO TICKETS) + +**Severity: HIGH** + +NPCs talk to the player (#168-174). But do NPCs talk to EACH OTHER? For the social simulation to feel alive, NPCs need to have conversations that the player can overhear, witness, or learn about. + +This is load-bearing for multiple claims: +- Fog of perception (hearing conversations through walls) +- NPCs alive off-screen (conversations happen without the player) +- Social triangles (confrontations are conversations) +- Observation mechanic (eavesdropping) + +**Proposed: NPC-to-NPC interaction system (high priority).** At minimum: NPCs in the same social site engage in visible conversation events with sound propagation. Content from the dialogue line pools. The player can approach to overhear more clearly. + +#### 4. NPC Reaction to Player Presence (PARTIALLY COVERED) + +**Severity: MEDIUM-HIGH** + +#115 gives NPCs vision. But what do they DO when they see the player? + +| Situation | Expected NPC reaction | Ticket coverage | +|-----------|----------------------|-----------------| +| Player enters NPC's workspace | Greeting, acknowledgment | Covered by dialogue #168-174 | +| Player follows NPC for too long | NPC becomes suspicious, changes behavior | NOT COVERED | +| Player is somewhere they shouldn't be | NPC challenges or reports player | NOT COVERED | +| Player interrupts a private conversation | NPCs stop talking, change topic | NOT COVERED | +| Player is witnessed doing something illicit | NPC reacts based on relationship/loyalty | NOT COVERED | + +The entire stealth/social-stealth dimension of the game depends on NPCs reacting to player behavior. This is partly a behavior system issue and partly a perception system issue. + +**Proposed: NPC player-awareness behavior (high priority).** NPCs track player presence using #115 vision. Suspicious behavior triggers are defined (following too long, unauthorized areas, witnessing secrets). Reactions use existing relationship/personality axes. + +#### 5. Time System (Q-009 OPEN — BLOCKS CRITICAL TICKETS) + +**Severity: CRITICAL BLOCKER** + +Daily routines (#88, critical priority) cannot be implemented without a time system. Tick-based game time needs to convert to in-game hours/days. The routine system needs to know "it's 3pm, NPC should be at the bar." + +Q-009 must be resolved before Sprint 1 of core simulation work begins. + +**Key design questions for the time system:** +- Tick-to-game-time ratio (how many ticks per game minute?) +- Time display (does the player see a clock? In-universe insert display?) +- Time-skip mechanics (can the player advance time? Sleep? Wait?) +- Event scheduling (how do time-based triggers work?) + +#### 6. Pathfinding (NO TICKETS) + +**Severity: HIGH** + +NPCs need to navigate the station district. They follow daily routines that move them between locations. They need to avoid walls, navigate corridors, and find paths to destinations. + +Godot has built-in NavigationServer2D, so this might be simpler than building from scratch. But it still needs: +- Navigation mesh setup for the station district +- NPC pathfinding integration +- Player movement collision + +**Proposed: NPC pathfinding story (high priority).** Leveraging Godot's nav system. + +#### 7. Save/Load System (NO TICKETS) + +**Severity: MEDIUM for v0.1 (HIGH for any release)** + +A 30-minute play session needs to be saveable. The state serialization system (#96, high) covers NPC state, but full game save includes: player position, game time, all NPC states, relationship states, information states, map state, dialogue history. + +**Proposed: save/load system story (medium priority for v0.1).** Can be deferred if v0.1 is treated as a demo that runs in one sitting. + +#### 8. Contamination Activation Mechanic (IMPLICIT BUT NOT TICKETED) + +**Severity: HIGH** + +D-027 says "contamination activates" — the smuggling ring's activities begin affecting the broader social ecosystem. But how? + +Mechanically, contamination means: +- An NPC in a mundane triangle starts behaving differently because they're now involved with the ring +- Information starts leaking between social sites via shared NPCs (#187) +- The detective's leads start pointing at NPCs the player has already met + +The storyteller (#162, LOW priority) was supposed to drive this. But if the storyteller is low priority, what activates contamination? A timer? A player action trigger? A systemic threshold? + +**Proposed: contamination activation mechanic (high priority).** This is the v0.1 equivalent of the storyteller — a simplified version that activates the smuggling ring's expansion at a defined point (possibly tied to game-time or player-progress thresholds). + +#### 9. Environmental Interaction States (NO TICKETS) + +**Severity: MEDIUM** + +Doors, terminals, containers, lights. Immersive sims need interactive environment elements. For v0.1, at minimum: +- Doors that open/close (NPC sightlines change, sound propagation changes) +- Maybe one terminal or document that can be read +- Lights that affect visibility + +Without these, the station district is a static diorama. NPCs walk through it, but the player can't interact with the space. + +**Proposed: basic environmental interaction story (medium priority).** Doors + one examinable object type. + +### Feedback Loop Gaps + +| Feedback type | How the player knows | Ticket coverage | +|---------------|---------------------|-----------------| +| Action had consequences | NPC behavior changes after player interaction | #103 (relationship dynamics, medium) — needs promotion? | +| Missed something | Monologue hints at unseen events | Partially #119-122, but needs authored content | +| Investigation progress | Knowledge state advancing toward threshold | NOT COVERED — no player-facing progress indicator | +| Reputation/standing | NPCs treat player differently based on accumulated behavior | #170 (relationship history, high) — partially covers this | +| Time pressure | Events happening that the player can't stop | NOT COVERED — requires time system + event scheduling | + +### Content Volume Feasibility + +| Content type | v0.1 volume estimate | Source | Risk | +|--------------|---------------------|--------|------| +| Authored dialogue lines | ~500-630 lines (3 templates x 165-210) | Mellanie #190-192 | Medium — tight but achievable | +| Generated dialogue lines | ~2,000-2,500 (4x expansion) | Generation pass #194 | Medium — quality of expansion matters | +| Monologue lines | ~200-400 (two characters, context-sensitive) | Not explicitly estimated | HIGH — monologue needs to feel SPECIFIC, not generic | +| NPC definitions | 20-30 NPCs with full 10-axis data | #92 NPC generation pipeline | Medium — pipeline should handle volume | +| Triangle definitions | ~6-9 triangles (2 per template + cross-template) | #106-108 | Low — manageable count | +| Environmental text | Signs, labels, terminal readouts, documents | NOT ESTIMATED | Medium — needs a ticket | +| Opening hook content | Character-specific starting events | NOT TICKETED | High — critical for first impression | + +**Monologue content is the highest content risk.** The monologue system carries an enormous burden in this game — it bridges perception gaps, creates atmosphere, provides hints, expresses character voice, and is the primary mechanism for the player understanding what's happening. If monologue lines feel generic or repetitive, the entire experience suffers. The current plan doesn't estimate monologue volume or call out monologue as a distinct content deliverable beyond the system tickets (#119-122). + +**Proposed: monologue content pack as explicit authoring deliverable (high priority).** Per character, per template, per situation. This is as important as the dialogue content packs. + +### Systems That Have Tickets But May Need Promotion + +| Ticket | Current Priority | Recommended Priority | Rationale | +|--------|-----------------|---------------------|-----------| +| #103 Relationship dynamics | Medium | **High** | Triangles can't activate without relationship state changes | +| #105 Tolerance threshold triggers | Medium | **High** | Only ticketed triangle activation mechanism | +| #102 Mood system | Medium | **High** | Mood affects dialogue selection (D-028) and NPC believability | +| #126 Medium-range visual indicators | Medium | **High** | Fog-edge tension depends on this — hearing things you can't see | +| #172 Unprompted disclosure (Layer 4) | Medium | **High** | NPCs need to volunteer information for the player to discover off-screen events | +| #162 Storyteller module activation | Low | **Medium** | Even a simplified version is needed for contamination | + +--- + +## Summary: Top 5 Systemic Risks for v0.1 + +| # | Risk | Impact if unaddressed | Proposed mitigation | +|---|------|----------------------|---------------------| +| 1 | **No player interaction verbs** beyond movement and dialogue | Player can see and hear the world but can't DO anything with it. 30 minutes of walking and talking. | New tickets: interaction framework, follow mechanic, examine mechanic | +| 2 | **No character objectives/motivation** | Player has no reason to go anywhere or do anything. Two characters with different views but no different drives. | New ticket: character goal/pressure framework | +| 3 | **Triangle activation gap** | Triangles are authored backstory that never produce observable events. Emergent drama claim fails. | Promote #103, #105 to high. New ticket: NPC confrontation behavior | +| 4 | **Time system unresolved** (Q-009) | Routines can't function, schedules can't exist, "daily life" concept breaks down. | Resolve Q-009 before Sprint 1 | +| 5 | **Monologue content underestimated** | Internal monologue carries the heaviest experiential burden in the game. Generic/thin monologue = flat experience. | New ticket: monologue content pack as distinct authoring deliverable | + +--- + +## Proposed New Tickets (Summary) + +| Title | Priority | Type | Rationale | +|-------|----------|------|-----------| +| Player interaction framework | Critical | Story | No way to interact with world beyond dialogue | +| Follow mechanic | High | Story | Required by D-027 criterion 4 | +| Examine mechanic | High | Story | Investigation requires inspecting objects | +| Wait/time-skip mechanic | Medium | Story | Stakeout/observation requires time control | +| Character goal/pressure framework | High | Story | Players need reasons to act | +| NPC-to-NPC conversation system | High | Story | Social simulation requires NPC-NPC interaction | +| NPC player-awareness behavior | High | Story | NPCs must react to player presence/behavior | +| NPC pathfinding | High | Story | NPCs must navigate the station district | +| Contamination activation mechanic | High | Story | D-027 concept requires this, storyteller is low priority | +| Opening hook content (per character) | High | Story | First 5 minutes need direction | +| Monologue content pack | High | Story | Distinct authoring deliverable, separate from system | +| Basic environmental interaction (doors, objects) | Medium | Story | World needs to be interactive, not decorative | +| Environmental text content | Medium | Story | Signs, terminals, documents for world-building | + +**Count: 13 new stories proposed.** This would bring the total to ~245. + +--- + +*Gestalt out. The systems are well-designed. The gap is in the verbs and events that make those systems produce gameplay. We built a beautiful engine — now we need to put wheels on it.* diff --git a/docs/workshops/v01-gap-analysis/round1-gore.md b/docs/workshops/v01-gap-analysis/round1-gore.md new file mode 100644 index 000000000..8db27c9f7 --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round1-gore.md @@ -0,0 +1,186 @@ +# Gap Analysis Workshop - Round 1: Gore (Themes & Endgame Design) + +## Track 1: Strength of Concept Proof - Thematic Evaluation + +### The Question Before the Questions + +Before I evaluate each claim, I need to name something. The v0.1 isn't proving six separate claims. It's proving one thesis with six facets: + +**"Who you are determines what is real."** + +Every claim in the table is a different angle on that sentence. Asymmetric information says reality is perspectival. Fog of perception says it physically. NPCs alive says the world doesn't conform to your presence. Observation as mechanic says knowing requires effort. Same world, different story says identity is destiny. Social triangles say other people's realities collide with yours. + +If the v0.1 proves that thesis as a *felt experience*, every claim is validated simultaneously. If it proves the claims as isolated mechanics, we've built six systems and zero games. The evaluation below is about whether the ticket plan creates a unified thematic experience or a feature checklist. + +--- + +### Claim 1: Asymmetric Information is the Core Mechanic + +**Thematic claim:** Truth is perspectival. What you know shapes what you *can* know. The detective and smuggler don't just see different facts — they live in different moral universes. + +**What the tickets deliver:** #138-142 (info boundaries) and #182-183 (divergent knowledge/relationships) are mechanically sound. The infrastructure for "different characters know different things" is there. + +**What's missing thematically:** The tickets build the *what* of asymmetric information but not the *why it matters*. The detective knows case files; the smuggler knows shipment schedules. Fine. But the thematic proof requires a moment where the player *realizes their knowledge was incomplete in a way that recontextualizes something they already experienced*. Not just "I didn't know X" but "I thought I understood this situation and I was wrong." + +This is the difference between a fog-of-war mechanic and an epistemological claim. The first hides information. The second makes the player question their own interpretation. The ticket plan hides information. The thematic promise is deeper. + +**Gap:** There's no ticket for what I'd call the "recontextualization moment" — the point where the player (ideally on a second playthrough as the other character) re-encounters a scene they thought they understood and realizes they were seeing shadows on the cave wall. The success criteria (#197) say "fundamentally different playthroughs" but don't specify *how the player discovers they were wrong*. The internal monologue system (#119-122) can carry this — the detective's monologue interpreting a scene the smuggler's monologue interpreted completely differently — but only if the content is authored with that specific reversal in mind. + +**Minimum bar for v0.1:** At least one scene/location where the smuggler and detective are both present (or observe the same event) and their internal monologues deliver contradictory but internally coherent interpretations. The player doesn't just see different facts — they see the same facts and draw different conclusions. That's the proof. + +**Risk: MEDIUM-HIGH.** Infrastructure is covered. The thematic proof depends on content authoring (#190-192) being deliberately designed around perspective reversal, which isn't called out in any ticket. + +--- + +### Claim 2: Fog of Perception Creates Tension + +**Thematic claim:** "You never see the full picture" — not as a limitation, but as a condition of existence. Uncertainty is the natural state. Certainty is the illusion. + +**What the tickets deliver:** #110-113 (shadowcasting to fog rendering) deliver the visual mechanic cleanly. You can't see behind walls. Fog returns. The screen literally shows you what you don't know. + +**What's missing thematically:** Fog is easy to read as a game mechanic — "I need to walk over there to see what's there." That's Civilization's fog of war. It's spatial ignorance, not existential uncertainty. The thematic claim requires the fog to feel like a *statement about the human condition*, not a rendering technique. + +The difference is: does the player think "I can't see over there" or do they think "what's happening over there *right now* that I don't know about?" The first is a mechanic. The second is paranoia. Paranoia is the thematic target. + +**How to close the gap:** The internal monologue (#119-122) is the bridge. When fog covers a location the player has been to before, the monologue should speculate. *"The docks are quiet. Usually that means nothing. Sometimes it means everything."* The fog isn't empty — it's full of the player's uncertainty. The sound model (#124-128) doubles down: sounds from beyond the fog give partial information that *could mean anything*. Footsteps that might be routine. Raised voices that might be an argument or might be a threat. + +The ticket plan has the ingredients. But the thematic weight depends on the monologue content (Mellanie's packs #190-192) and the sound system working in concert. No ticket explicitly ties fog + monologue + sound into a unified uncertainty experience. + +**Minimum bar for v0.1:** One moment where the player hears something from beyond their fog, their monologue interprets it ambiguously, and they have to decide whether to investigate. That's the thematic proof: uncertainty as a decision-forcing condition. + +**Risk: MEDIUM.** The systems exist. The thematic payoff depends on content integration that's implicit, not planned. + +--- + +### Claim 3: NPCs Feel Alive Without Player Attention + +**Thematic claim:** "The world doesn't revolve around you." Stronger: "The world doesn't *need* you." You are one consciousness among many, each pursuing their own answer to the question of what life is for. + +**What the tickets deliver:** #88 (daily routines), #93-99 (simulation tiers), #101 (routine execution). NPCs have schedules. They go to work, eat, socialize, sleep. The simulation continues when you're not watching. + +**Does the contentment axis (D-024) come through?** This is my main concern. The contentment axis — whether an NPC is satisfied with their current life — is the thematic heartbeat of the population. It's what connects each individual NPC to the game's central question. But in the ticket plan, contentment appears as part of the NPC data model (#86-90) without any system that *expresses* it to the player. + +A contented bartender and a restless bartender should *feel* different. Not through a UI label, but through behavior: the contented one whistles while working, talks about the regulars, is genuinely present. The restless one stares out the window, brings up topics from other worlds, checks their insert during quiet moments. The tell system (#90) could carry this, but only if contentment is specifically authored as a tell dimension. + +**Gap:** The player needs to *notice* that NPCs have inner lives. Routine execution (#101) makes them move on schedule. But thematic aliveness requires behavioral texture — small tells that reveal an NPC's relationship to their own existence. This lives in the intersection of the tell system (#90), monologue hooks (content packs #190-192), and routine execution (#101). No ticket owns that intersection. + +**Minimum bar for v0.1:** At least two NPCs whose contentment level is legibly different through behavior (not UI). The player should be able to say "that person seems happy" or "that person seems restless" without being told. The monologue can editorialize: *"She seems at peace here. Must be nice."* or *"He keeps looking at the gate schedule. Doesn't strike me as the vacationing type."* + +**Risk: MEDIUM.** The data model supports it. The behavioral expression depends on content authoring awareness of the contentment axis as a *visible* dimension, not just a simulation variable. + +--- + +### Claim 4: Observation is a Mechanic, Not a Cutscene + +**Thematic claim:** To know something, you must watch, listen, and interpret. Knowledge is earned through attention. But watching makes you a participant — not neutral, not innocent. + +**What the tickets deliver:** #115 (NPC vision), #124-128 (sound model), #119-122 (internal monologue). The player can see, hear, and think about what they observe. Mechanically solid. + +**The ethical dimension:** This is the claim I want to push hardest on. The detective is, by job description, a *watcher*. They observe NPCs' routines, track their movements, overhear their conversations. The smuggler does something similar in reverse — watching for surveillance, monitoring who's paying attention. + +Neither character asked for permission. The game *rewards you for watching people*. That's the same power dynamic as surveillance, and the v0.1 should make the player feel the weight of it — not as guilt, but as *awareness*. You're the one watching. Nobody knows. Is what you're learning worth what it costs to learn it this way? + +**What's missing:** No ticket addresses the player's relationship to the act of observation itself. The observation mechanic is treated as pure gameplay — see, deduce, act. But the thematic claim is richer: observation is ethically loaded. The monologue can carry this. When you overhear a private conversation through a wall, the monologue shouldn't just report content — it should register that you're eavesdropping. *"Not my business. But useful."* or *"She doesn't know I can hear this."* These lines turn a mechanic into a moral texture. + +**Gap:** The ethical dimension of watching is absent from the ticket plan. It's a content/writing concern, not a systems concern, but it needs to be called out as a content requirement in the monologue specifications. + +**Minimum bar for v0.1:** At least one instance where the player learns something by observing that they arguably shouldn't know, and the monologue acknowledges the transgression. The detective overhears a personal conversation and gets useful intel. The smuggler watches a colleague's routine to identify a vulnerability. The mechanic works. The monologue makes you feel it. + +**Risk: LOW-MEDIUM.** Systems are complete. The ethical texture is a content authoring note, easily addressable. + +--- + +### Claim 5: Same World, Different Story + +**Thematic claim:** Identity shapes reality. Who you ARE determines what you EXPERIENCE. Not just what you know — what you *notice*, what you *care about*, what *threatens* you. + +**What the tickets deliver:** #179-183 (character builds), #196-199 (success criteria). Two characters, divergent knowledge, divergent relationships. The plan says the two playthroughs should feel like "fundamentally different games." + +**This is the deepest claim the v0.1 makes.** And the ticket plan undersells it. "Different starting knowledge" and "different relationships" produce different *facts*. But the thematic claim is about different *realities*. The detective walks into the logistics hub and sees a potential crime scene. The smuggler walks into the same logistics hub and sees their workplace. Same tiles, same NPCs, same lighting. Utterly different meaning. + +**How meaning diverges:** It's not just information asymmetry (claim 1). It's *interpretive framing*. The same NPC behavior — say, a colleague staying late — means different things depending on who's watching. The detective thinks: *"Working late. Or meeting someone they don't want to be seen with."* The smuggler thinks: *"Kai's pulling overtime again. Covers for the shipment window."* Same observation, different narrative universe. + +This requires the internal monologue to be *character-specific in interpretation*, not just in knowledge. Ticket #121 (character voice variation) gestures at this but its scope appears to be tonal ("voice") rather than interpretive ("framing"). The smuggler's monologue interprets the world through the lens of someone maintaining cover. The detective's interprets through the lens of someone looking for cracks. Same stimulus, different cognition. + +**Gap:** Character voice variation (#121) needs to be explicitly scoped as *interpretive framing*, not just tone. The success criterion (#197) needs to specify that "fundamentally different" means *the player's understanding of the same events diverges*, not just that they experience different events. + +**Minimum bar for v0.1:** One shared location where both characters spend significant time (the logistics hub is the obvious candidate). The same NPC does the same thing. The two characters' monologues interpret it differently. On a second playthrough, the player realizes the first playthrough's interpretation was not wrong — just partial. Neither character had the full picture. Both were right. Both were incomplete. + +**Risk: MEDIUM-HIGH.** This is the hardest claim to prove and the most important. The systems support it, but the proof lives in content design that's aware of the dual-interpretation requirement. No ticket explicitly owns "same observation, different meaning." + +--- + +### Claim 6: Social Triangles Create Emergent Drama + +**Thematic claim:** Human relationships are inherently unstable. Three people with overlapping needs and conflicting interests will, given time, produce situations no one planned. The game's drama comes from *people*, not plots. + +**What the tickets deliver:** #106-109 (triangle generation), #175-176 (entanglement ratio). Triangles are defined, generated within and across templates, and validated. The 30/50/20 entanglement ratio (D-029) ensures most triangles are mundane. + +**Do mundane triangles carry thematic weight?** This is the critical question. A neighbor dispute about noise. A workplace rivalry over a promotion. A bartender caught between two friends who hate each other. These triangles don't involve conspiracies. They embody the "is this enough?" question in miniature: these people's lives are *about* these small conflicts. Their world is the noise, the promotion, the friendship. For them, these aren't small. They're everything. + +The mundane triangles ARE the thematic ground floor. The game argues — through the sheer *volume* of mundane human drama — that ordinary life is dense with meaning. The 50% mundane triangle population isn't filler. It's the thesis statement. + +**Gap:** The ticket plan treats mundane triangles as noise (D-029: "investigation signal requires noise floor"). Mechanically accurate. Thematically backward. The mundane triangles need to be *interesting on their own terms*, not just camouflage for conspiracy triangles. This means the content packs (#190-192) need to treat mundane triangle scenarios with the same authorial care as intrigue triangles. A workplace rivalry should be written as a *story*, not a distraction. + +**Minimum bar for v0.1:** At least one mundane triangle that the player can engage with on its own terms. Help resolve a neighbor dispute. Take sides in a workplace rivalry. Notice that two people at the bar have history. The player should be able to spend time on this and feel it was *worth doing*, not a distraction from "the real game." If mundane triangles feel like noise, the 30/50/20 ratio becomes a design liability instead of a thematic strength. + +**Risk: MEDIUM.** Triangle generation is covered. The thematic proof depends on content quality for mundane scenarios, which is a writing and authoring priority. + +--- + +## Claims the Game SHOULD Be Making at v0.1 + +### The Surveillance/Privacy Tension + +The detective is a surveillance agent. The smuggler is a surveillance target. Neither character operates in a world that respects privacy — the Settled Reach has insert tracking, camera networks, institutional databases. The player participates in a surveillance ecosystem from both sides. + +The v0.1 should make the player *feel* this. Not as a mechanic (perception modes handle that later) but as a thematic undercurrent. The detective's tools — observation, tracking, overhearing — are the same tools the state uses on its citizens. The smuggler's tools — counter-surveillance, information compartmentalization, social camouflage — are the same tools dissidents use. + +**Is the player complicit?** That's the question the v0.1 should plant. Not answer. Plant. The internal monologue can carry it: the detective occasionally noting that what they're doing isn't so different from what the people they investigate do. The smuggler noting that their employers watch them just as closely as the authorities. + +**Ticket impact:** This is a content requirement for monologue hooks in the character builds (#180-181) and content packs (#190-192). No new systems needed. + +### The "Quiet Life is Valid" Thesis (D-029) + +D-029 says the unentangled majority must feel valid, not cowardly. The v0.1 must prove this. If the mundane NPCs feel like set dressing and the entangled NPCs feel like "the real game," the thesis collapses. + +The proof is in whether the player finds the 80% of the population who aren't involved in anything *interesting to observe*. Not because they're suspects — because they're people. The coffee vendor's morning routine. The colleague's lunch habits. The bartender's relationship with the regulars. + +**Ticket impact:** The v0.1 success criteria (#196-199) don't include "player found the unentangled population interesting." They should. Success criterion #198 says "player names an NPC they felt conflicted about." I'd add: "player names an NPC they found interesting who had nothing to do with the intrigue." That's the quiet life proof. + +### Character Identity as Constructed (Death = Information Loss, D-008) + +D-008 says death costs you memories since your last backup. This is an identity question: are you the same person if you lose six months of experience? The v0.1 probably shouldn't implement the full backup mechanic — but it should plant the seed. + +The monologue can do this. A passing reference to the character's backup schedule. A reflection on what they'd lose if something happened. *"Last backup was three months ago. A lot's happened since then."* This connects the player's accumulated knowledge and relationships to the character's sense of self. What you know IS who you are. Losing it isn't death — it's erasure. + +**Ticket impact:** A content note for character builds (#180-181). Two or three monologue lines, maximum. No systems work. + +### The Cost of Knowing + +This is the claim that ties everything together and I don't see it anywhere. + +Investigation isn't free. The detective who watches people learns things they can't unlearn. The smuggler who maintains a cover has to lie to people they might actually like. Both characters pay a price for what they know — not in hit points or resources, but in what their knowledge does to their relationships and their self-image. + +The v0.1 should hint at this cost. The detective's monologue should occasionally register discomfort with what they've learned. The smuggler's monologue should register the weight of deception. These aren't gameplay mechanics — they're the beginnings of the game's deeper argument that *all knowledge changes the knower*. + +**Ticket impact:** Content guidance for character voice in #121 and monologue hooks in #190-192. + +--- + +## Summary: Concept Proof Scorecard + +| Claim | Ticket Coverage | Thematic Delivery | Risk | Key Gap | +|-------|----------------|-------------------|------|---------| +| Asymmetric information | Strong | Medium | MEDIUM-HIGH | Needs "recontextualization moment" — same event, contradictory interpretations | +| Fog of perception | Strong | Medium | MEDIUM | Fog + monologue + sound need explicit integration as uncertainty system | +| NPCs alive | Strong | Medium | MEDIUM | Contentment axis needs visible behavioral expression, not just data | +| Observation as mechanic | Strong | Medium-Low | LOW-MEDIUM | Ethical dimension of watching absent from specs | +| Same world, different story | Good | Low | MEDIUM-HIGH | Character voice variation must be interpretive framing, not just tone | +| Social triangles | Good | Medium | MEDIUM | Mundane triangles need authorial investment equal to intrigue triangles | + +**Overall assessment:** The ticket plan builds a strong *mechanical* foundation for all six claims. The thematic delivery gap is almost entirely a *content and authoring* problem, not a systems problem. The systems are right. What's missing is explicit guidance to the content team (Mellanie, Miri, Paula) that the monologue, dialogue, and NPC behaviors must be authored with the thematic claims in mind — not just the mechanical ones. + +**The single biggest risk:** Claim 5 (same world, different story) is the hardest to prove and the most important. If the two playthroughs feel like "different starting loadouts" instead of "different realities," the v0.1 has failed its thesis. This requires the internal monologue to be *interpretively divergent*, not just informationally divergent. Same scene, two characters, two fundamentally different understandings of what they're witnessing. That's the proof of concept. Everything else is scaffolding. + +**One new ticket recommendation:** A cross-cutting story or content guide: "Dual Interpretation Authoring Guide" — explicitly mapping the shared locations, shared events, and shared NPCs that both characters encounter, with authored monologue and behavioral variations showing how the same reality looks from two different identities. This is the document that turns the v0.1 from a systems demo into a thematic statement. Assign to Gore (thematic framing) + Mellanie (authoring) + Paula (narrative depth). diff --git a/docs/workshops/v01-gap-analysis/round1-hoshe.md b/docs/workshops/v01-gap-analysis/round1-hoshe.md new file mode 100644 index 000000000..ab85bbf01 --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round1-hoshe.md @@ -0,0 +1,675 @@ +# Round 1: Testability Deep-Dive (Track 4) — Hoshe + +**Workshop:** v0.1 Gap Analysis Workshop +**Agent:** Hoshe (QA Engineer) +**Date:** 2026-02-11 +**Scope:** Full testability initiative (#34, epics #61-#64, stories #200-#217) + cross-initiative testing needs + +--- + +## 1. Test Architecture for Agent-Driven Development + +The core constraint: Claude Code agents write tests, run tests, and interpret results. Everything flows from that. + +### What works for agents + +**Simple invocation.** One command, no interactive prompts, no GUI. The ideal is: +```bash +simulation/test.sh # runs all Rust tests +simulation/test.sh perception # runs one module +client/test.sh # runs all Godot tests +test-integration.sh # runs IPC + sync tests +``` +Wrapper scripts, like the existing `db/connectors/sqlite-*` pattern. Agent types command, gets back structured output. No environment detective work. + +**Structured output with failure context.** Agents need: +- Pass/fail per test (not just a summary count) +- Failure message with assertion details (expected vs actual) +- File path + line number of the failure +- Test name that maps to what was being tested (not `test_17`) + +**Deterministic results.** Flaky tests are agent poison. An agent can't distinguish "test is flaky, retry" from "I broke something." Every test must produce the same result given the same inputs. This has implications for the simulation (see section on determinism below). + +**Fast feedback.** Agents work in edit-test cycles. If the test suite takes 30 seconds, that's 30 seconds of wasted context window per iteration. Target: full Rust unit tests < 5s, individual test < 100ms. + +**Self-contained tests.** No external service dependencies, no database state to set up, no network calls. Tests create their own world, run, assert, tear down. bevy_ecs is naturally good at this (create a World, add components, run system, inspect components). GDScript is harder — scene trees have lifecycle assumptions. + +### Recommended test structure + +``` +simulation/ + src/ + perception/ + mod.rs + shadowcast.rs + vision_cone.rs + perception/tests/ # unit tests per module (or inline #[cfg(test)]) + tests/ + integration/ # multi-system integration tests + perception_chain.rs # shadowcast -> vision cone -> observer query + npc_behavior.rs # routine + mood + relationship interaction + tier_transitions.rs # active -> background -> state-saved + determinism/ # replay-based determinism tests + benchmarks/ # criterion benchmarks + +client/ + test/ # gdUnit4 tests (see section 3) + unit/ + scene/ + integration/ + +protocol/ + tests/ # serialization round-trip, schema compat + +scripts/ + test-rust.sh # wraps cargo test/nextest with output formatting + test-godot.sh # wraps godot --headless with gdUnit4 + test-integration.sh # spins up real subprocess, runs protocol tests + test-all.sh # runs everything, returns combined report +``` + +--- + +## 2. Rust Testing: Inline vs External Test Crate + +### Recommendation: Hybrid approach + +**Inline `#[cfg(test)]` for unit tests within each module.** Rationale: +- Direct access to private functions and internal state +- Tests live next to the code they test — agents can read both in one file +- Zero boilerplate: `cargo test` finds them automatically +- bevy_ecs systems typically have small, focused functions that test well inline + +```rust +// simulation/src/perception/shadowcast.rs + +pub fn compute_visibility(origin: IVec2, range: i32, map: &TileMap) -> HashSet { + // ... implementation +} + +#[cfg(test)] +mod tests { + use super::*; + use bevy::prelude::*; + + #[test] + fn empty_room_full_visibility() { + let map = TileMap::empty(10, 10); + let visible = compute_visibility(IVec2::new(5, 5), 5, &map); + // All tiles within range should be visible + assert!(visible.contains(&IVec2::new(5, 6))); + assert!(visible.contains(&IVec2::new(3, 3))); + } + + #[test] + fn wall_blocks_vision() { + let mut map = TileMap::empty(10, 10); + map.set_wall(5, 6); + let visible = compute_visibility(IVec2::new(5, 5), 5, &map); + assert!(visible.contains(&IVec2::new(5, 6))); // wall itself is visible + assert!(!visible.contains(&IVec2::new(5, 7))); // behind wall is not + } +} +``` + +**Separate `tests/` directory for integration tests.** These test system interactions, multi-tick behavior, and cross-module concerns: + +```rust +// simulation/tests/integration/perception_chain.rs + +use bevy::prelude::*; +use simulation::perception::*; +use simulation::components::*; + +#[test] +fn observer_sees_entity_in_los() { + let mut world = World::new(); + + // Set up minimal world + let observer = world.spawn(( + Position(IVec2::new(5, 5)), + VisionCone { range: 10, facing: Direction::North }, + Observer, + )).id(); + + let target = world.spawn(( + Position(IVec2::new(5, 8)), + Visible, + NpcMarker, + )).id(); + + // Run perception systems + let mut schedule = Schedule::default(); + schedule.add_systems(( + compute_shadowcast_system, + apply_vision_cone_system, + generate_observer_snapshot_system, + ).chain()); + schedule.run(&mut world); + + // Assert observer can see target + let snapshot = world.get::(observer).unwrap(); + assert!(snapshot.visible_entities.contains(&target)); +} +``` + +**Why not a separate test crate?** For our project size (one developer + agents), the indirection of a separate crate adds complexity without benefit. Inline + integration directory covers all needs. A separate test crate makes sense when you need to test the public API boundary of a library — our simulation isn't a published crate, it's an application. + +### bevy_ecs-specific testing patterns + +**Pattern 1: World + Schedule for system tests** +Create a `World`, spawn test entities, build a `Schedule` with the systems under test, call `schedule.run(&mut world)`, assert on component state. This is the bread-and-butter pattern. + +**Pattern 2: App for multi-tick tests** +For tests that need multiple simulation ticks (tier transitions, behavior over time): +```rust +let mut app = App::new(); +app.add_plugins(MinimalPlugins); +app.add_systems(Update, (system_a, system_b).chain()); +app.world_mut().spawn(/* test entities */); + +// Simulate N ticks +for _ in 0..10 { + app.update(); +} + +// Assert state after N ticks +``` + +**Pattern 3: Resource injection for determinism** +Replace RNG, time, and external inputs with test-controlled resources: +```rust +// Production: reads real time +// Test: inject frozen or stepped time +app.insert_resource(SimulationTime::fixed(GameTime::new(8, 0, 0))); // 8 AM +``` + +**Critical for #201 (deterministic replay):** The simulation MUST consume time, randomness, and player input exclusively through injectable resources. No `std::time::Instant`, no `rand::thread_rng()` — everything goes through a `SimRng` resource seeded from the world seed. This isn't test infrastructure — it's a production architecture requirement (D-010 principle 4: deterministic simulation with input events). + +--- + +## 3. Godot Testing: GUT vs gdUnit4 + +### Recommendation: gdUnit4 + +| Criterion | GUT | gdUnit4 | Winner | +|-----------|-----|---------|--------| +| **CLI/headless** | `godot -d -s --path . addons/gut/gut_cmdln.gd` | `GdUnitCmdTool` built-in CLI | gdUnit4 (cleaner interface) | +| **Output format** | JUnit XML, console text | JUnit XML, HTML, JSON summaries | gdUnit4 (JSON for agents) | +| **Scene testing** | Basic | `GdUnitSceneRunner` with input simulation, time control | gdUnit4 (much richer) | +| **Mocking** | Doubler system | Code-gen mocking + spy builder | gdUnit4 (more capable) | +| **Assertions** | Good basics | 13 specialized assertion types including Godot-native | gdUnit4 (exhaustive) | +| **CI integration** | JUnit XML + exit codes | GitHub Action (`gdunit4-action`), JUnit XML + HTML | gdUnit4 (turnkey CI) | +| **Maintenance** | Single maintainer (bitwes) | Organization (godot-gdunit-labs) | gdUnit4 (bus factor) | +| **Known issues** | Headless mode issues (#491 on GitHub) | Stable headless support | gdUnit4 | +| **Agent friendliness** | Good | Better (JSON output, structured reports) | gdUnit4 | + +### Can we realistically run Godot tests from Claude Code? + +**Yes, with caveats.** + +The invocation would be: +```bash +godot --headless --path client/ -s addons/gdUnit4/bin/GdUnitCmdTool.gd --test-suite test/unit/ +``` + +**Caveats:** +1. **Godot must be installed and on PATH** on the dev machine. This is a tooling requirement for ticket #216. +2. **Headless mode doesn't render.** We can't visually verify fog rendering or sprite placement from automated tests. Rendering verification (#208) is limited to asserting shader parameters, visibility flags, node properties — not pixel output. +3. **Scene lifecycle.** GDScript tests that need `_ready()`, `_process()`, or signal connections require `GdUnitSceneRunner` to simulate the scene tree lifecycle. Direct function tests are simpler but limited. +4. **Import cache.** First run after project changes requires Godot to rebuild the import cache, which can take seconds. Subsequent runs are fast. + +**What we CAN test in Godot client (pure renderer, no game logic per D-020):** +- MessagePack deserialization (GDScript side) +- ObserverSnapshot → scene tree mapping +- Fog overlay parameter calculation +- UI widget state from HUD data +- Input capture → PlayerInput serialization +- Sound event → audio playback trigger + +**What we CANNOT effectively test in headless Godot:** +- Visual correctness of fog rendering (needs eyes or screenshot comparison) +- Audio output correctness (headless has no audio device) +- Frame rate / rendering performance + +**Wrapper script for agents:** +```bash +#!/bin/bash +# client/test.sh - Godot test runner for agent use +godot --headless --path client/ \ + -s addons/gdUnit4/bin/GdUnitCmdTool.gd \ + --test-suite "${1:-test/}" \ + --report-format json \ + 2>&1 +exit $? +``` + +--- + +## 4. Integration Testing + +### IPC Protocol Tests (#210) + +**Recommendation: Both mock and real, layered.** + +**Layer 1 — Serialization round-trip (mock, fast, in Rust + GDScript separately):** +``` +Rust: ObserverSnapshot → MessagePack bytes → ObserverSnapshot (assert equality) +GDS: MessagePack bytes → Dictionary → MessagePack bytes (assert equality) +Cross: Rust-serialized bytes → GDScript deserialize → assert field values +``` +The cross-language test is the critical one. Run it by having Rust write test fixtures (MessagePack binary files), then GDScript tests read and verify them. No subprocess needed. + +**Layer 2 — Protocol sequence (mock subprocess):** +Test the protocol state machine: handshake → tick loop → snapshot delivery → input receipt → error recovery. Use a mock Rust process that sends predetermined sequences. This tests the GDScript `LocalBridge` without real simulation. + +**Layer 3 — Real subprocess (integration, slower):** +Launch actual simulation binary, send actual inputs, verify actual snapshots. This is the end-to-end truth. Run less frequently (not every edit cycle). + +```bash +# test-integration.sh +# Layer 1: fixture-based (fast) +cargo test -p protocol --lib # Rust serialization +godot --headless --path client/ -s ... --test-suite test/protocol/ + +# Layer 2: mock subprocess (medium) +cargo test -p protocol --test mock_bridge + +# Layer 3: real subprocess (slow, nightly) +cargo test -p integration --test real_bridge -- --ignored +``` + +### Sync Verification (#211) — Testing Determinism + +**This is the hardest testing problem in the project.** + +Deterministic simulation means: same seed + same input sequence = same state at every tick. Testing this requires: + +1. **Record & replay infrastructure (#201):** + - Record: capture (tick_number, input_event) pairs during a test run + - Replay: feed the same inputs, compare state at each tick + - Compare: serialize ECS world state to a canonical hash at each tick + +2. **Canonical state hashing:** + - Sort all entities deterministically (by entity ID or stable identifier) + - Hash all component values in deterministic order + - Compare hashes across runs + +3. **Known pitfalls that break determinism:** + - HashMap iteration order (use BTreeMap or sort before hashing) + - Floating-point accumulation (prefer fixed-point or integer math for game logic) + - System execution order (bevy schedules must be explicit, not ambiguous) + - Entity allocation order after despawn/respawn cycles + +4. **Test pattern:** +```rust +#[test] +fn deterministic_over_100_ticks() { + let seed = 42u64; + let inputs = load_test_inputs("basic_movement.inputs"); + + let hash_1 = run_simulation(seed, &inputs, 100); + let hash_2 = run_simulation(seed, &inputs, 100); + + assert_eq!(hash_1, hash_2, "Simulation diverged: non-deterministic behavior detected"); +} +``` + +5. **Regression strategy:** Store golden hashes for known input sequences. If a code change alters a golden hash, the test fails. Developer must either fix the non-determinism or deliberately update the golden hash (with justification). + +**v0.1 scope:** Record/replay for Rust simulation only. Godot client determinism is not required (it's a pure renderer — visual jitter doesn't affect game state). + +### Full Playthrough Automation (#212) + +**Is this realistic for v0.1? Partially.** + +What IS realistic: +- **Scripted input sequences:** "Walk north 10 tiles, wait 5 ticks, interact with NPC at (20, 15), select dialogue option 1." These exercise the full stack without AI. +- **Smoke tests:** Launch game, verify no crash after 60 seconds of simulated input. Verify NPC entities exist. Verify ObserverSnapshot contains expected fields. +- **Milestone validation:** "Start as smuggler. Walk to logistics hub. Verify hub NPCs are visible. Verify monologue triggers." These are semi-automated acceptance tests. + +What is NOT realistic for v0.1: +- **AI-driven playthroughs:** We don't have an AI player that can navigate, make decisions, and evaluate outcomes. +- **Full 30-minute playthroughs:** Too slow for CI, too complex to script meaningfully. +- **"Fun" automation:** The D-027 success criteria include subjective measures (emotional attachment, emergent observation). These need human playtesters. + +**Recommendation:** Build the scripted input infrastructure (#212) but scope it to smoke tests and milestone checkpoints, not full playthroughs. Full playthrough testing is manual playtesting with structured reports (see section 7). + +--- + +## 5. Test Output Format + +### Recommendation: JUnit XML as interchange + JSON summaries for agents + +**Why not one format?** + +- **JUnit XML** is the universal CI standard. GitHub Actions, GitLab CI, Jenkins — they all render it natively. Both gdUnit4 and cargo-nextest can produce it. It's the right format for CI dashboards and historical tracking. +- **JSON** is what agents parse fastest. An agent reading JUnit XML needs to understand a slightly awkward schema. A simple JSON summary is immediately actionable. + +**Proposed wrapper output (what agents actually see):** + +```json +{ + "suite": "simulation::perception", + "timestamp": "2026-02-11T14:30:00Z", + "duration_ms": 247, + "total": 15, + "passed": 14, + "failed": 1, + "skipped": 0, + "failures": [ + { + "test": "vision_cone_peripheral_range", + "file": "simulation/src/perception/vision_cone.rs", + "line": 142, + "message": "assertion failed: `(left == right)`\n left: 12\n right: 15", + "expected": "peripheral range should be 15 tiles", + "actual": "computed range was 12 tiles" + } + ] +} +``` + +**Implementation:** The wrapper scripts (`test-rust.sh`, `test-godot.sh`) run the native test runners, capture JUnit XML output, and post-process into this JSON summary format. This is a small Python or Rust CLI tool — ticket it under #216 (tooling requirements). + +**cargo-nextest** is the recommended Rust test runner over plain `cargo test`: +- Runs tests in separate processes (better isolation) +- JUnit XML output with `--message-format libtest-json` (experimental) or `nextest-run --junit-xml` +- Faster parallel execution +- Better failure output formatting + +--- + +## 6. Production Code Constraints (#217) + +### The principle: Test seams through architecture, not annotations + +The D-020 architecture (subprocess/IPC, client-server separation) already creates the primary test seam: the protocol boundary. Anything that crosses that boundary is testable by mocking one side. + +### Rust/bevy_ecs: Naturally testable, minimal pollution needed + +bevy_ecs is inherently test-friendly: +- **Systems are functions.** They take queries and resources as parameters. Inject different resources → different behavior. No special test hooks needed. +- **Components are data.** Spawn whatever entities you want in a test World. No factory pattern, no dependency injection framework. +- **Resources are swappable.** Replace `Time` with a test time. Replace `SimRng` with a seeded RNG. This is standard bevy, not test pollution. + +**Acceptable seams in Rust production code:** +- `SimRng` resource wrapping RNG (required for determinism anyway — D-010 principle 4) +- `SimulationTime` resource wrapping time (required for determinism) +- `SimBridge` trait abstracting transport (required for multiplayer-ready architecture — D-010) +- `#[derive(Debug, PartialEq)]` on components (needed for assertions, zero runtime cost) +- Public visibility on types that tests need to construct (use `pub(crate)` not `pub`) + +**Unacceptable pollution:** +- `#[cfg(test)]` conditional logic in production systems +- Test-only components in the production ECS +- Feature flags that alter simulation behavior for testing +- Mock traits wrapping concrete types just for testability + +### GDScript: Harder, needs clear boundaries + +GDScript's scene tree model is less naturally testable than ECS. The key problems: +- Node lifecycle (`_ready`, `_process`) only runs inside the scene tree +- Signals are tied to the tree structure +- Autoloads create implicit global state + +**Strategy for testable GDScript:** + +1. **Separate logic from nodes.** Pure functions that take data and return data: + ```gdscript + # Good: testable without scene tree + static func parse_observer_snapshot(data: PackedByteArray) -> Dictionary: + return MessagePack.decode(data) + + # Bad: needs full scene tree + func _on_snapshot_received(): + var data = bridge.read() + update_entities(data) + update_fog(data) + ``` + +2. **Data classes / Resources for state.** GDScript `Resource` classes are serializable, inspectable, and don't need the scene tree. + +3. **Scene runner for integration tests.** Use `GdUnitSceneRunner` when you MUST test node lifecycle — but keep these tests few and focused. + +4. **No game logic in GDScript.** Per D-020, the client is a pure renderer. The less logic in GDScript, the less needs testing there. Push all game logic to Rust, where testing is natural. + +**The line:** If you find yourself adding testability hooks to GDScript, you're probably putting logic in the wrong place. Move it to Rust and test it there. + +--- + +## 7. Success Criteria Validation (#60 / D-027) + +### Criterion 1: "30-minute daily-life breathing room" (#196) + +**Can this be automated? Partially.** + +Automated test: +- Start simulation with test seed, smuggler character +- Advance simulation clock to 30 in-game minutes +- Assert: contamination module activation event has NOT fired +- Assert: at least N routine events have occurred (NPCs going to work, socializing) +- Assert: at least N monologue triggers have fired (character is experiencing daily life) + +```rust +#[test] +fn contamination_does_not_activate_before_30_minutes() { + let mut app = build_vertical_slice_app(Seed(42), Character::Smuggler); + + // Simulate 30 minutes of game time + for _ in 0..(30 * 60 * TICKS_PER_SECOND) { + app.update(); + } + + let storyteller = app.world().resource::(); + assert!(!storyteller.contamination_activated(), + "Contamination activated before 30-minute runway"); +} +``` + +**What automation CAN'T test:** Whether those 30 minutes are *interesting*. That's a human playtest question. But we can verify the mechanical guarantee: the storyteller doesn't rush. + +**Playtest protocol needed:** Structured form with timestamp markers: "At minute 5, what were you doing? At minute 15? At minute 25? Were you bored? When?" + +### Criterion 2: "Fundamentally different playthroughs" (#197) + +**Can this be automated? Yes, comparatively.** + +Run two simulations with the same seed but different characters. Compare: + +| Metric | Smuggler run | Detective run | Test assertion | +|--------|-------------|---------------|----------------| +| Starting known NPCs | Set A | Set B | A != B (at least 50% different) | +| Starting known POIs | Set C | Set D | C != D | +| NPC relationship valences | Positive toward smuggling ring | Suspicious of smuggling ring | Inverted signs | +| Accessible dialogue lines (tick 0) | Insider lines available | Authority lines available | Non-overlapping access tiers | +| Monologue on same NPC | "Good old [name]" | "Subject of interest" | Different voice/content | +| Visible information (same location) | Knows cargo contents | Sees suspicious behavior | Different ObserverSnapshot fields | + +```rust +#[test] +fn smuggler_and_detective_see_different_worlds() { + let seed = Seed(42); + let smuggler_snapshot = run_initial_snapshot(seed, Character::Smuggler); + let detective_snapshot = run_initial_snapshot(seed, Character::Detective); + + // Known NPCs should differ + let overlap = smuggler_snapshot.known_npcs.intersection(&detective_snapshot.known_npcs); + assert!(overlap.count() < smuggler_snapshot.known_npcs.len() / 2, + "Characters know too many of the same NPCs — not divergent enough"); + + // Relationship valences toward smuggling ring NPCs should be inverted + for npc in smuggling_ring_npcs(seed) { + let s_val = smuggler_snapshot.relationship_valence(npc); + let d_val = detective_snapshot.relationship_valence(npc); + assert!(s_val.signum() != d_val.signum(), + "Smuggler and detective have same relationship valence toward {npc:?}"); + } +} +``` + +**This is one of the most automatable success criteria.** The divergence is structural, not subjective. + +### Criterion 3: "Emotional NPC attachment" (#198) + +**Can this be automated? No.** + +This is a subjective, emotional response. "Can you name an NPC you felt conflicted about?" requires a human brain that experienced narrative tension. + +**What we CAN automate as proxies:** +- Verify NPCs have sufficient axis data to BE interesting (10 axes present, contradictions exist) +- Verify relationship dynamics change over time (not static) +- Verify monologue references NPCs by name with emotional coloring +- Verify dialogue layers unlock over time (surface → real → secret) +- Count unique NPC interactions per 30-minute session (minimum threshold) + +**What we MUST do manually:** +- Post-playtest survey: "Name an NPC. What do you know about them? Did they surprise you?" +- Track if players remember NPC names unprompted +- Track if players hesitate before actions that affect specific NPCs + +**Playtest protocol:** Minimum 5 playtesters (can be team members in different sessions). Structured debrief form. Key question: "Which NPC would you feel bad about betraying?" + +### Criterion 4: "Emergent observation mechanics" (#199) + +**Can this be automated? The chain can be verified; emergence cannot.** + +The required chain: observe → notice → follow → discover. + +**Automated verification:** +- **Observe:** Player's ObserverSnapshot contains NPC entity at some tick. (Logged.) +- **Notice:** Monologue system fires a notice trigger about that NPC's behavior. (Logged event with cause chain.) +- **Follow:** Player moves toward NPC's location in subsequent ticks. (Input log analysis.) +- **Discover:** Player gains new information (information inventory changes). (State diff.) + +```rust +#[test] +fn observation_chain_is_system_driven_not_scripted() { + // Run simulation with scripted player input that follows an NPC + let log = run_with_inputs(Seed(42), Character::Detective, &follow_suspicious_npc_inputs()); + + // Verify the discovery event has a system-generated cause chain + let discovery = log.events.iter() + .find(|e| e.event_type == EventType::InformationGained) + .expect("No discovery event occurred"); + + // The cause chain should trace back to perception, not a script trigger + assert!(!discovery.cause_chain.contains(&Cause::ScriptedReveal), + "Discovery was scripted, not emergent"); + assert!(discovery.cause_chain.contains(&Cause::VisualObservation) + || discovery.cause_chain.contains(&Cause::AudioObservation), + "Discovery should originate from a perception event"); +} +``` + +**The "emergent" part is harder.** Emergence means the sequence wasn't pre-authored. We can verify: +- No hard-coded "if player is at location X, trigger revelation Y" +- The NPC's suspicious behavior comes from their routine + secret, not a script +- The monologue notice comes from the monologue system's standard triggers, not a special case + +**Recommendation:** Add a `CauseChain` component to information gain events. Every piece of new information tracks HOW it was learned. If any chain includes `Cause::ScriptedReveal`, that's a test failure for this criterion. This is a small production code addition that serves both debugging and criterion validation. + +--- + +## 8. Cross-Initiative Testing Gaps + +Systems NOT in the testability initiative (#34) that need test coverage: + +### Pathfinding (NOT IN ANY TICKET) +NPCs need to navigate. There's no pathfinding ticket anywhere in the 232-ticket catalog. This is a Track 3 gap, but from a testing perspective: pathfinding is one of the most testable systems (input: start + end + obstacles, output: path). We need the ticket before we can write tests. + +**Testing need:** Path validity (no wall clipping), path optimality (no absurd routes), performance (A* on 150x150 within tick budget). + +### Collision Detection (NOT IN ANY TICKET) +Same gap. Player and NPC movement needs collision. Testable: entity at position A moves toward wall, verify entity stops. + +### Time System (Q-009 — UNRESOLVED) +Daily routines (#88) depend on a time system. The deterministic replay system (#201) depends on controllable time. We can't write tests for time-dependent behavior until Q-009 is resolved. + +**Testing need:** Time advancement determinism, routine triggers at correct game-time, tier eviction timing (D-026). + +### Information Boundary Verification (#138-142) +These are in the Map & Navigation initiative, not testability. But information boundary correctness IS the most critical test target in the game — it's the core mechanic (D-010 principle 2, D-011). + +**Testing need:** Exhaustive negative testing. "Entity X CANNOT see component Y of entity Z." Information leak = game-breaking bug. This should be the most heavily tested subsystem in the entire project. + +Proposed test pattern: +```rust +#[test] +fn smuggler_cannot_see_detective_case_notes() { + let world = setup_vertical_slice(Seed(42)); + let smuggler_snapshot = generate_snapshot(&world, Character::Smuggler); + let detective = find_entity(&world, "detective_character"); + + // Smuggler's snapshot should not contain detective's investigation data + assert!(!smuggler_snapshot.has_component_data(detective, ComponentType::CaseNotes), + "Information boundary violated: smuggler can see detective's case notes"); +} +``` + +### NPC Generation Validation (#92 / D-024) +NPC generation needs validation tests: do generated NPCs actually have all 10 axes? Do triangles form? Are contradictions present? + +**Testing need:** Statistical validation over N generation runs. "Given seed X, do at least 2 triangles form per template? Does every NPC have a non-empty Secret?" + +### Dialogue System (#168-174 / D-028) +The line previewer (#193) is explicitly called out as a regression test harness. But we also need: +- Tag filtering tests: "Does an outsider character get insider dialogue?" (must fail) +- Layer progression tests: "After N positive interactions, does trust-gated content unlock?" +- Trait modifier tests: "Does the same base line read differently with different personality traits?" + +### Save/Load (NOT IN ANY TICKET) +Not testable until it exists, but flagging: save/load is a classic source of bugs. Serialization round-trip tests (save state → load state → compare) should be written the moment the system exists. + +--- + +## 9. Priority Adjustments + +Based on this analysis, I recommend the following priority changes: + +| Ticket | Current | Recommended | Reason | +|--------|---------|-------------|--------| +| #214 (Refinement discussion) | Critical | Critical | **Confirmed.** This workshop IS the discussion. Unblocks everything else. | +| #201 (Deterministic replay) | High | **Critical** | Without determinism, sync tests (#211) and divergence tests (#197) are impossible. Blocks multiple success criteria. | +| #210 (IPC protocol tests) | High | High | Confirmed. Layer 1 (fixture-based) should be built alongside #76/#77. | +| #211 (Sync verification) | High | High | Confirmed, but blocked by #201. | +| #212 (Full playthrough automation) | Medium | **Low for v0.1** | Scope to smoke tests only. Full automation isn't realistic. | +| #213 (Performance profiling) | Low | Low | Confirmed. Nice to have, not blocking. | +| #208 (Rendering verification) | Medium | **Low** | Headless Godot can't meaningfully verify rendering. Defer to manual. | +| #207 (Input simulation) | Medium | **High** | Required for scripted smoke tests and integration testing. | + +### New tickets needed (suggest to Si): +1. **Pathfinding test plan** — blocked by pathfinding implementation ticket (which doesn't exist) +2. **Information boundary negative test suite** — high priority, core mechanic validation +3. **Test output formatter CLI** — transforms JUnit XML to agent-friendly JSON +4. **Playtest protocol definition** — structured form for manual D-027 criteria validation +5. **CauseChain component for information events** — supports criterion 4 automation + +--- + +## 10. Summary of Recommendations + +| Question | Recommendation | +|----------|---------------| +| Rust test organization | Hybrid: inline `#[cfg(test)]` for unit tests, `tests/` directory for integration | +| Rust test runner | cargo-nextest (parallel, isolated, JUnit XML output) | +| Godot test framework | gdUnit4 (better CLI, JSON output, scene runner, maintained) | +| IPC tests | Three layers: fixture (fast), mock subprocess (medium), real subprocess (slow) | +| Determinism testing | Record/replay with canonical state hashing. Promote #201 to critical. | +| Playthrough automation | Smoke tests only for v0.1. Full automation is premature. | +| Test output format | JUnit XML for CI + JSON summary for agents. Wrapper scripts handle conversion. | +| Production code constraints | Architecture provides seams naturally. No `#[cfg(test)]` in production. Move logic out of GDScript. | +| Criterion 1 (30-min runway) | Automated: verify no contamination before 30 min. Manual: verify it's interesting. | +| Criterion 2 (divergent plays) | Automated: compare snapshots across characters. Most automatable criterion. | +| Criterion 3 (emotional attachment) | Manual only. Automate proxies (axis presence, interaction count). Playtest protocol required. | +| Criterion 4 (emergent observation) | Semi-automated: verify cause chains are system-driven, not scripted. Add CauseChain component. | + +--- + +## References + +- [Bevy System Testing Patterns](https://bevy-cheatbook.github.io/patterns/system-tests.html) +- [gdUnit4 Repository](https://github.com/godot-gdunit-labs/gdUnit4) +- [GUT Command Line Documentation](https://gut.readthedocs.io/en/latest/Command-Line.html) +- [cargo-nextest Machine-Readable Output](https://nexte.st/book/machine-readable.html) +- [Automated Testing in Bevy](https://chadnauseam.com/coding/gamedev/automated-testing-in-bevy/) diff --git a/docs/workshops/v01-gap-analysis/round1-nigel.md b/docs/workshops/v01-gap-analysis/round1-nigel.md new file mode 100644 index 000000000..d4d27e64f --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round1-nigel.md @@ -0,0 +1,323 @@ +# Workshop Round 1 - Nigel: Sandbox & Replayability Analysis + +## Track 1: Strength of Concept Proof — "What happens the SECOND time you play this?" + +--- + +### Claim 1: Asymmetric Information Is the Core Mechanic + +**Tickets:** #138-142 (info boundaries), #182-183 (divergent knowledge/relationships) + +**Playthrough 2 analysis:** + +Player plays smuggler first. Learns the ring, the contacts, the dead drops. Then plays detective. They KNOW who's dirty. Can they use that knowledge? + +**My answer: metagaming is a FEATURE, not a bug — but only if the system doesn't let it trivialize the game.** + +Dramatic irony is one of the most powerful emotions in storytelling. Playing the detective KNOWING the smuggling operation from the inside is compelling. The player thinks "I know who you are" when they see an NPC — but can the detective CHARACTER act on that? No. The information boundaries (#138-142) gate what the detective can officially know, investigate, or act on. The player's knowledge creates TENSION, not shortcuts. + +BUT — and this is where D-029 earns its keep — the entanglement ratio varies per seed. So playthrough 3 (detective, different seed) is a player who THINKS they know the pattern from playthroughs 1 and 2, but the ratio has shifted. The bar owner who was innocent in seed A is complicit in seed B. Player overconfidence becomes a trap. That's anti-metagaming gold. + +**Ticket coverage: 7/10** + +The info boundary system is well-ticketed. What's missing: +- No ticket for "metagaming-as-dramatic-irony" — the system should be designed to reward, then subvert, cross-playthrough knowledge. This is an authoring consideration for Mellanie's content packs: include NPCs who LOOK guilty to a metagaming player but aren't in some seeds. +- #182 (divergent starting knowledge) and #183 (divergent relationships) are HIGH not CRITICAL. For replayability proof, these ARE critical. If both characters start with similar knowledge, the "different game" feeling collapses immediately. + +**Risk: MEDIUM.** The architecture supports replayability. The content needs to actively exploit it. + +--- + +### Claim 2: Fog of Perception Creates Tension + +**Tickets:** #110-113 (shadowcasting to fog rendering) + +**Playthrough 2 analysis:** + +The honest question: does the player learn the map once and fog becomes meaningless? + +**Short answer: at v0.1 scale, partially yes. And that's okay IF the NPCs vary.** + +The station district is a fixed layout. After playthrough 1, the player knows where walls are, where rooms are, where sightlines exist. Fog doesn't hide ARCHITECTURE the second time. What fog hides is ACTIVITY — who is where, what they're doing, what's happening behind that wall right now. + +This means fog's replayability value depends ENTIRELY on NPC routine variation. If the bar owner is always at the bar at 8pm, the fog over the bar at 8pm communicates nothing new on playthrough 2. If the bar owner is sometimes at a secret meeting at 8pm (seed-dependent), fog creates genuine uncertainty even for returning players. + +**Critical dependency:** Fog replayability = f(routine variation). Ticket #88 (daily routine system) is critical priority but its scope description needs to ensure seed-based timing variation. Ticket #178 (seed-based variation) is LOW priority. This is a problem. + +**Ticket coverage: 6/10** + +The fog SYSTEM is well-covered. The fog EXPERIENCE on replay is not. What's missing: +- No explicit connection between seed-based NPC schedules and fog-discovery variation +- #156 (procedural district filler) at MEDIUM could help — even minor spatial shuffles (furniture placement, blocked corridors, construction zones) would make fog rediscovery meaningful +- No ticket for "fog memory decay" testing — D-011 says fog returns when you leave, but there's no validation that this creates genuine re-exploration + +**Risk: HIGH for replay, LOW for first playthrough.** Fog will work beautifully on playthrough 1. Its replay value hinges on NPC variation that's currently underpriotitized. + +--- + +### Claim 3: NPCs Feel Alive Without Player Attention + +**Tickets:** #88 (daily routines), #93-99 (simulation tiers), #101 (routine execution) + +**Playthrough 2 analysis:** + +**The bar owner question: is the bar owner always at the bar?** + +With the 10-axis NPC model (D-024), each NPC's daily routine is ONE of 10 axes, generated per seed via the NPC generation pipeline (#92). So in theory, the bar owner in seed A has a different routine than the bar owner in seed B. + +But wait — the bar owner IS the bar owner because they own the bar. Their ROLE constrains their routine. The bar template (#185) defines a role that includes "operates the bar." Can you have a bar owner who's rarely at the bar? That creates its own interesting dynamics (who's covering? what are they doing instead?), but it also risks breaking template coherence. + +**What should vary between runs:** +- **Routine timing** — same activities, different schedule. Bar opens at different times per seed. Meeting happens Tuesday vs Thursday. +- **Routine deviations** — some seeds, the bar owner takes walks at midnight. Others, they drink in their office after closing. These are the secrets you discover through observation. +- **Relationship-driven changes** — if the bar owner and the logistics hub manager are in a triangle, their routines INTERACT differently per seed based on relationship state. +- **Entanglement effects** — an entangled bar owner has secret meeting routines that an unentangled one doesn't. + +**Ticket coverage: 7/10** + +The simulation tier system (#93-99) is well-designed and the background state machines mean NPCs genuinely change while you're not watching. Routine execution (#101) makes them act on those states. But: +- #88 (daily routine system) doesn't explicitly require seed-based VARIATION in routines +- #92 (NPC generation pipeline) is HIGH not CRITICAL — this is the pipeline that creates per-seed variation! +- No ticket for routine DEVIATION mechanics (what makes an NPC break their routine?) +- #105 (tolerance threshold triggers) is MEDIUM — but tolerance threshold crossings ARE the moments that create "alive without attention" proof + +**Risk: MEDIUM.** The tier system architecture is sound. The routine generation needs to be explicitly designed for variation. + +--- + +### Claim 4: Observation Is a Mechanic, Not a Cutscene + +**Tickets:** #115 (NPC vision), #124-128 (sound model), #119-122 (internal monologue) + +**Playthrough 2 analysis:** + +**Can the observe-notice-follow-discover chain produce DIFFERENT discoveries in different runs?** + +The chain: +1. **Observe** — see NPC behavior through fog (vision system) +2. **Notice** — internal monologue flags something unusual (monologue system) +3. **Follow** — player decides to tail the NPC (player agency + NPC routines) +4. **Discover** — find the secret (information boundary reveal) + +For this chain to vary per run, EACH link needs to produce different outputs: +- **Observe**: Different NPCs in different places (seed-dependent) = YES varies +- **Notice**: Different tells (#90) flagged by monologue = DEPENDS on tell variation per seed +- **Follow**: Different destinations (routine variation) = DEPENDS on #88 seed design +- **Discover**: Different secrets (D-029 entanglement variation) = YES varies + +The chain's ENDPOINTS vary well (different conspiracies, different entangled NPCs). The chain's MIDPOINTS — what tells look like, how the monologue interprets them — need more variation. + +**Critical gap:** The tell system (#90) is HIGH priority and is load-bearing for observation replayability. If "hesitating before answering" always means guilt, players learn the meta. Tells need to vary per seed — some seeds, hesitation is meaningful; others, it's just a personality trait. D-029's variable entanglement helps here, but the tell POOL needs to be rich enough that the same behavior doesn't always map to the same meaning. + +**Ticket coverage: 6/10** + +The mechanical pipeline exists. What's missing: +- Tell variation per seed — not explicitly in #90's scope +- Monologue variation for returning players — does the character notice DIFFERENT things on different runs? #121 (character voice variation) helps but is MEDIUM priority +- No "false positive" mechanic — observation should sometimes lead to dead ends. Unentangled NPCs with suspicious-looking routines are essential anti-metagaming +- #123 (unreliable narrator) is LOW priority but is a replayability multiplier — different characters interpret the same observation differently + +**Risk: HIGH.** The observe chain WORKS once. For it to work differently on replay, tell variation and false positives need explicit design attention. + +--- + +### Claim 5: Same World, Different Story + +**THE critical claim for replayability. This is my hill.** + +**Tickets:** #179-183 (character builds), #196-199 (success criteria) + +#### Playthroughs 1 & 2: Smuggler vs Detective (same seed) + +**Rating: 8/10** + +This is well-designed. The smuggler's daily life IS the detective's investigation target. Same NPCs, same locations, inverted relationships. The smuggler knows who's in the ring and sees the detective as a threat. The detective sees suspicious patterns and the smuggler as either a suspect or a potential informant. + +D-027 specifically requires "both playthroughs feel like fundamentally different games." Tickets #180 (smuggler build) and #181 (detective build) are CRITICAL. Divergent starting knowledge (#182) and relationships (#183) are HIGH. + +**What makes this work:** +- Different ACCESS TIERS to the same dialogue (D-028 layer 1) — smuggler gets insider talk at the docks, detective gets deference at the precinct +- Different TRIANGLES are visible — smuggler sees criminal triangles, detective sees institutional ones +- Different MONOLOGUE voice — same NPC behavior, different character interpretation +- Different ROUTINE relevance — the smuggler cares about shift changes (opportunity windows), the detective cares about pattern deviations (suspicious activity) + +**What could undermine this:** +- If the station district is too small, the spatial experience is identical. Both characters walk the same corridors to the same 3 locations. The SOCIAL experience differs but the PHYSICAL experience doesn't. +- If dialogue content (#190-192 content packs) doesn't have enough access-tier variation, conversations feel similar despite different character builds + +#### Playthroughs 3 & 4: Same characters, different seed + +**Rating: 4/10 — THIS IS THE GAP** + +Here's where I start shouting. + +There is NO ticket that explicitly validates "same character, different seed = different experience." Ticket #197 (criterion 2: fundamentally different playthroughs) tests smuggler vs detective. It does NOT test smuggler-seed-A vs smuggler-seed-B. + +What SHOULD change per seed: +- Which NPCs are entangled (D-029) — **#175, #176 are MEDIUM priority, should be HIGH** +- Which Tier 1 module is active (D-023) — **#158 is MEDIUM priority and only Tier 1 drama module schema, not the pool draw** +- Which NPCs fill which template roles (#92, #176) — **#176 is MEDIUM, should be HIGH** +- Triangle configurations (#106-109) — **#107 is HIGH, good** +- Tell assignments (#90) — **variation per seed not explicitly scoped** +- Routine timing (#88) — **variation per seed not explicitly scoped** + +**The seed-based variation ticket (#178) is LOW priority. This is the single biggest replayability risk in the entire v0.1 plan.** + +Without #178, playthroughs 3 and 4 are playthroughs 1 and 2 with different characters. The replay ceiling drops from 6-8 runs to exactly 2. + +**Ticket coverage for cross-seed replay: 4/10** + +**Risk: CRITICAL.** The ticket plan proves two-CHARACTER replayability but not two-SEED replayability. The infrastructure exists in the decisions (D-023, D-029) but the implementation tickets are underpriotitized. + +--- + +### Claim 6: Social Triangles Create Emergent Drama + +**Tickets:** #106-109 (triangle generation), #175-176 (entanglement ratio) + +**Playthrough 2 analysis:** + +**Do triangles generate differently across seeds?** + +With the triangle generation system (#106-109), triangles are defined at template level (2 intra-template, 1 cross-template per site). With 3 social sites, that's at minimum 9 triangles involving ~20 NPCs. + +The combinatorial question: how many MEANINGFULLY DIFFERENT triangle configurations are possible with ~20 NPCs and 3 sites? + +Each triangle needs 3 NPCs with specific relational properties. With 20 NPCs: +- 3 sites x 4-8 NPCs each = 12-24 role slots +- Intra-template triangles draw from within site (C(8,3) = 56 possible per large site) +- Cross-template triangles connect across sites +- Per-seed NPC generation (#92) fills roles differently each time + +**Theoretical variety: HIGH.** The combinatorial space is large enough for 10+ meaningfully different configurations. + +**Practical variety: MEDIUM.** Role constraints reduce the effective space. The "bar owner and two regulars" triangle has limited configurations because the role structure constrains who can be involved. The triangle TYPES may repeat even as specific NPCs change. + +**Player-created triangles:** NOT COVERED IN TICKETS. + +This is a gap. If the player befriends two NPCs who hate each other, that's a player-created triangle. If the player becomes a regular at the bar and the bar owner starts treating them as a confidant, that reshapes existing triangles. The relationship dynamics system (#103) is MEDIUM priority and might support this implicitly, but there's no explicit design for player-inserted triangle dynamics. + +**Ticket coverage: 6/10** + +Triangle generation is reasonably covered. What's missing: +- Player as triangle vertex — no ticket +- Triangle DISSOLUTION mechanics — what happens when a triangle resolves? New one forms? +- Cross-seed triangle variety validation — are triangle types diverse enough? +- #108 (cross-template triangles) is MEDIUM but cross-template triangles are where the most surprising emergent stories come from + +**Risk: MEDIUM.** Triangle generation will work. Triangle SURPRISE across playthroughs depends on role flexibility and NPC pool variety. + +--- + +## Special Evaluation: D-029 Entanglement Ratio (30/50/20) + +**Does variable entanglement actually prevent metagaming?** + +YES — but only if the variance is wide enough and the tell system cooperates. + +**The math at v0.1 scale (~20 NPCs):** +- 30% flat = 6 NPCs (wallpaper, routine + greeting only) +- 50% mundane triangles = 10 NPCs (real drama, no conspiracy connection) +- 20% entangled = 4 NPCs (conspiracy-linked) + +With variance (say 25-35/45-55/15-25 per seed): +- Low-entanglement seed: 3 entangled NPCs out of 20. Investigation is a needle-in-haystack. +- High-entanglement seed: 5 entangled NPCs out of 20. More suspects, faster discovery, but more red herrings too. +- The module attachment ratio (60-70/30-40 known vs stranger) further varies WHICH 3-5 are entangled. + +**The anti-metagaming effect:** A player who calibrated "roughly 1 in 5 NPCs is suspicious" from playthrough 1 finds that calibration WRONG on playthrough 2. They can't build a reliable suspicion threshold. The uncertainty IS the replay value. + +**Gap:** Tickets #175 (entanglement ratio configuration) and #176 (NPC pool generation) are MEDIUM. For anti-metagaming to work at v0.1, these need to be HIGH. The variable ratio is meaningless if it's not implemented. + +**Risk: MEDIUM.** The design is sound. The implementation priority doesn't match the design's importance. + +--- + +## Special Evaluation: Seed-Based Variation (#178) + +**Is this sufficient for replayability at v0.1 scale?** + +**#178 is LOW priority. This is insufficient. Full stop.** + +Seed-based variation is not a nice-to-have for replayability — it IS replayability. Without it, the game has exactly two meaningfully different playthroughs (smuggler + detective). With it, the game has 6-8+ meaningfully different playthroughs. + +What #178 needs to control at v0.1: +1. **NPC role assignment** — which generated NPCs fill which template roles +2. **Entanglement selection** — which NPCs are conspiracy-linked (D-029) +3. **Entanglement ratio** — what percentage of NPCs are entangled per seed (D-029 variance) +4. **Triangle configuration** — which NPCs form which triangles +5. **Routine timing offsets** — same routine types, different schedules per seed +6. **Tell assignment** — which behavioral tells are meaningful vs personality quirks +7. **Module attachment** — which Tier 1 module(s) activate and which NPCs they attach to + +Items 1-4 are architectural (the seed determines generation outputs). Items 5-7 are behavioral (the seed determines how the world FEELS different). + +**Recommendation: PROMOTE #178 to HIGH. Split into sub-tasks if needed. This is the replayability engine.** + +--- + +## Replay Ceiling Estimate + +**Station district: 3 social sites, ~20 NPCs, 2 characters** + +| Scenario | Playthroughs | Confidence | +|----------|-------------|------------| +| Without seed variation | 2 (one per character) | HIGH — smuggler vs detective is well-designed | +| With seed variation (current LOW priority) | 4-6 | MEDIUM — depends on variation breadth | +| With seed variation + tell variety + routine offsets | 6-8 | MEDIUM — diminishing returns from small NPC pool | +| With all above + player-created triangles | 8-10 | LOW — speculative, needs mechanic design | + +**For a v0.1 vertical slice, 6-8 meaningfully different playthroughs is excellent.** Most vertical slices are one-and-done. But we only get there if seed-based variation is properly prioritized. + +**The comparison test:** Can two players describe completely different games? +- Smuggler vs detective: YES, absolutely +- Same character, different seed (current plan): MAYBE — not enough ticket coverage +- Same character, same seed, different play choices: PARTIALLY — social triangles create some divergence, but the conspiracy structure is fixed per seed + +--- + +## Summary: Priority Adjustment Recommendations + +### PROMOTE (replayability-critical, currently underpriotitized) + +| Ticket | Current | Recommended | Reason | +|--------|---------|-------------|--------| +| #178 Seed-based variation | LOW | **HIGH** | The replayability ENGINE. Without it, replay ceiling = 2 | +| #175 Entanglement ratio config | MEDIUM | **HIGH** | D-029 anti-metagaming requires implementation | +| #176 NPC pool generation | MEDIUM | **HIGH** | Per-seed NPC assignment is foundational | +| #182 Divergent starting knowledge | HIGH | **CRITICAL** | Core differentiator between characters | +| #183 Divergent relationships | HIGH | **CRITICAL** | Core differentiator between characters | +| #108 Cross-template triangles | MEDIUM | **HIGH** | Where the most surprising emergent stories come from | + +### NEW TICKETS NEEDED + +1. **Same-character-different-seed validation test** — Success criterion alongside #197. Two smuggler playthroughs with different seeds must produce measurably different experiences. +2. **Tell variation per seed** — Extend #90 to ensure behavioral tells are seed-dependent, not fixed. Hesitation doesn't always mean guilt. +3. **Routine timing variation per seed** — Extend #88 to include seed-based schedule offsets. Same routine types, different timing. +4. **False positive design** — Unentangled NPCs with suspicious-looking (but innocent) routines. Essential anti-metagaming. +5. **Player-as-triangle-vertex** — Mechanic for player actions to create or modify social triangles. + +### CONCEPT PROOF SCORECARD + +| Claim | First Playthrough | Second Playthrough (other char) | Third+ (same char, new seed) | Overall Risk | +|-------|-------------------|--------------------------------|------------------------------|-------------| +| Asymmetric information | 9/10 | 8/10 | 6/10 | MEDIUM | +| Fog of perception | 9/10 | 5/10 | 5/10 | HIGH (replay) | +| NPCs alive | 8/10 | 7/10 | 5/10 | MEDIUM | +| Observation as mechanic | 8/10 | 6/10 | 5/10 | HIGH | +| Same world, different story | 9/10 | 8/10 | 4/10 | **CRITICAL** | +| Social triangles | 8/10 | 7/10 | 6/10 | MEDIUM | + +### Bottom Line + +**The v0.1 plan proves the two-character concept beautifully. It does NOT yet prove the replayability concept.** + +Playthroughs 1 and 2 (smuggler vs detective) will deliver. The architecture is sound, the information boundaries are well-designed, and the character-as-lens approach creates genuinely inverted experiences. + +But playthroughs 3 and beyond — same characters, different seeds — are where The Settled Reach's long-term value lives. And that's where the ticket plan has its biggest gap. Seed-based variation (#178) at LOW priority, entanglement configuration (#175) at MEDIUM, NPC pool generation (#176) at MEDIUM — these are the tickets that turn a two-play demo into a replayable game. + +The DECISIONS are right. D-023 (pool-based modules), D-029 (variable entanglement), the variable attachment ratios — these are brilliant anti-metagaming designs. But the tickets that IMPLEMENT those decisions are deprioritized relative to their importance. + +**My single most important recommendation: promote #178 (seed-based variation) from LOW to HIGH.** Everything else is incremental improvement. This one change is the difference between "play it twice" and "play it eight times." + +And it nails replayability without us engineering it! The SYSTEMS do the work. We just need to make sure the seed reaches deep enough into those systems. diff --git a/docs/workshops/v01-gap-analysis/round1-ozzie.md b/docs/workshops/v01-gap-analysis/round1-ozzie.md new file mode 100644 index 000000000..69c6d0b1d --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round1-ozzie.md @@ -0,0 +1,382 @@ +# Workshop Round 1 - Ozzie's Analysis +## Track 1: Strength of Concept Proof + Track 2: Fun & Wow Factor + +--- + +## TRACK 1: STRENGTH OF CONCEPT PROOF + +### How I'm rating these: +Each claim gets two scores: +- **Systemic delivery** (will the tickets build it?) — 1 to 5 +- **Emotional delivery** (will the player FEEL it?) — 1 to 5 + +A claim can score 5/5 systemic and 1/5 emotional. That means it works but nobody cares. That's a failed concept proof. + +--- + +### Claim 1: "Asymmetric information is the core mechanic" +**Proof:** Smuggler and detective see the same world differently. +**Tickets:** #138-142 (info boundaries), #182-183 (divergent knowledge/relationships) + +**Systemic: 4/5** — The information boundary system (#138-142) is well-specced. Component-level access control (#139), entity visibility filtering (#140), knowledge-based gating (#141). This is the plumbing. It'll work. + +**Emotional: 3/5** — Here's my worry. Information boundaries are INVISIBLE by definition. The player doesn't know what they can't see. That's the POINT, but it's also the PROBLEM. How does the player FEEL the asymmetry? + +The answer is: they feel it when they SWITCH characters. Play smuggler, then detective. THEN you go "oh my god, THAT'S what was happening." But that means the WOW moment is deferred to the SECOND playthrough. For the first playthrough, asymmetric info manifests as... confusion? Mystery? That can work — Outer Wilds did it — but we need the first playthrough to feel intriguing, not frustrating. + +**What's missing:** There's no "mirror moment" ticket. No moment in the FIRST playthrough where the player glimpses the other side. The smuggler overhears the detective asking questions. The detective finds evidence the smuggler left behind. Something that whispers "there's a whole other game here." The internal monologue system (#119-122) COULD deliver this — "Who the hell was asking about shipment schedules at the bar?" — but it's not explicitly designed for it. + +**Verdict:** Solid foundation, needs a first-playthrough emotional anchor. + +--- + +### Claim 2: "Fog of perception creates tension" +**Proof:** Player doesn't know what they can't see. +**Tickets:** #110-113 (shadowcasting to fog rendering) + +**Systemic: 5/5** — Clean dependency chain. Shadowcasting (#110) feeds vision cone (#111) feeds observer query (#112) feeds fog rendering (#113). This is the most technically complete chain in the whole catalog. + +**Emotional: 4/5** — THIS is where the game becomes a game. Fog of perception is horror-game DNA applied to a detective sim. Every corner is a question mark. Every building you walk past has people DOING THINGS you can't see. The vision cone (#111) means you can be SNUCK UP ON. + +I can already feel it. You're tailing an NPC through the station. They turn a corner. You follow. The fog peels back and — they're gone. Where did they go? Your monologue fires: "They were right here. I saw them turn this way." THAT'S the game. + +**What could push this to 5/5:** Sound through walls. The three-range sound model (#124-128) is specced, and #124 (sound event system) is high priority. But #128 (sound propagation physics) is LOW priority. That means sounds don't propagate THROUGH structures in v0.1. You might hear footsteps in the fog... but you won't hear a conversation through a wall. That specific moment — pressing against a wall, hearing muffled voices, making a decision — is a SIGNATURE moment and it's deprioritized. + +**Verdict:** Strong. Promote #128 or at minimum ensure #124-126 can deliver wall-muffled audio cues. + +--- + +### Claim 3: "NPCs feel alive without player attention" +**Proof:** Routines continue, relationships shift off-screen. +**Tickets:** #88 (daily routines), #93-99 (simulation tiers), #101 (routine execution) + +**Systemic: 4/5** — The simulation tier system (#93-99) is well thought out. Active NPCs run full sim. Background NPCs tick state machines. The timestamp eviction model means NPCs you interact with stay active. Solid. + +**Emotional: 2/5** — AND HERE'S MY BIGGEST CONCERN. + +NPCs feel alive when you NOTICE they were alive without you. You leave the bar at 6pm. You come back at 10pm. The bartender is talking to someone new. The couple in the corner has been replaced by a lone drinker. That's the SYSTEMIC delivery. But does the player NOTICE? + +In a top-down view with placeholder art (#133), NPCs are sprites. Small sprites. Moving between locations on schedules. Unless the game TELLS the player what changed — through monologue ("Hmm, Kira's not at her usual spot tonight"), through dialogue ("You just missed Marcus — he left about an hour ago"), through observable state changes (the bar rearranges, lights shift) — the player will never feel NPC life happening. + +**What's missing:** There's no "noticing change" system. No ticket for the character observing and reacting to differences in routine. The monologue system (#119-122) COULD do this but the monologue event generation (#119) doesn't specifically target routine deviation. Routine EXECUTION is #101 (high priority). But routine DEVIATION DETECTION — noticing when an NPC breaks their pattern — isn't a ticket at all. AND THAT'S THE ACTUAL DETECTIVE MECHANIC. + +Let me say that again louder: **NOTICING THAT AN NPC BROKE THEIR ROUTINE IS THE CORE GAMEPLAY LOOP AND IT'S NOT A TICKET.** + +**Verdict:** The simulation will run. The player won't feel it without a deviation detection + monologue bridge. This needs a new ticket, and it needs to be HIGH priority. + +--- + +### Claim 4: "Observation is a mechanic, not a cutscene" +**Proof:** Player deduces from watching, overhearing, noticing. +**Tickets:** #115 (NPC vision), #124-128 (sound model), #119-122 (internal monologue) + +**Systemic: 3/5** — The pieces are here but loosely connected. NPC vision (#115) tells us NPCs can see things. Sound model (#124-128) tells us sounds propagate. Monologue (#119-122) tells us the character comments. But where's the OBSERVATION VERB? What does the player DO to observe? + +Is it passive? (Just stand and watch, and the monologue fires automatically?) Is it active? (Press a button to "focus" on an NPC, getting more detailed observations?) Is it positional? (Get close enough and your character overhears things?) + +The workshop brief (Track 3) flags this: "Player can move, look, listen — but what can they DO?" I agree. There's no interaction system ticket for directed observation. + +**Emotional: 3/5** — Observation as a mechanic lives or dies on FEEDBACK. You stand outside a building. You can see in through a window. An NPC hands something to another NPC. Your monologue says: "That looked like it might have been a data chip. Or maybe just payment for drinks." THAT moment — where the game tells you "you saw something but you're not sure what" — THAT'S the game. + +But that moment requires: vision system + NPC behavior happening in viewable space + monologue triggering on observed events + ambiguity in the monologue. Each of these is a different system and none of them are wired together in the ticket plan. + +**What's missing:** An "observation event pipeline" — when the player's character observes a notable NPC action, generate a monologue event with uncertainty based on distance/clarity/knowledge. This is the SPINE of the game and it's spread across 4 epics with no connecting tissue. + +**Verdict:** The systems exist in isolation. Needs an integration story that wires observation → interpretation → monologue into a single gameplay loop. High priority. + +--- + +### Claim 5: "Same world, different story" +**Proof:** Two playthroughs are mechanically distinct. +**Tickets:** #179-183 (character builds), #196-199 (success criteria) + +**Systemic: 4/5** — Character builds (#179-181) define the smuggler and detective. Divergent starting knowledge (#182) and relationships (#183) ensure they enter the world differently. The social site templates (#184-186) will be experienced from opposite sides. + +**Emotional: 5/5** — THIS IS THE KILLER FEATURE AND WE NEED TO PROTECT IT AT ALL COSTS. + +The smuggler walks into the logistics hub and sees his coworkers. The detective walks into the same logistics hub and sees suspects. Same NPCs. Same relationships. COMPLETELY different emotional register. The smuggler's best friend IS the detective's prime suspect. THAT'S the game. + +This is the thing you show people. This is the "holy shit" moment. "I played as the smuggler and I liked this guy, he was my work buddy, we had drinks together. Then I played as the detective and I found out he was — oh my god." + +**What could go wrong:** If the two characters feel like reskins — same verbs, same access, same daily experience — the mechanical distinction falls flat. The character builds (#180-181) need to deliver genuinely different DAILY ROUTINES, not just different starting knowledge. The smuggler hauls cargo. The detective reviews case files. Different rhythms, different spaces, different NPCs they spend time with during the mundane 30 minutes. + +**Verdict:** The strongest emotional claim. Protect it. Ensure #180 and #181 define radically different daily experiences, not just different stat sheets. + +--- + +### Claim 6: "Social triangles create emergent drama" +**Proof:** NPC relationships produce situations designers didn't script. +**Tickets:** #106-109 (triangle generation), #175-176 (entanglement ratio) + +**Systemic: 3/5** — Triangle definition (#106) and generation (#107-108) are specced. But triangle ACTIVATION — the moment where a triangle produces a player-facing event — isn't clearly ticketed. Triangles generate NPC configurations. But what makes those configurations FIRE? When does the workplace rivalry escalate? When does the love triangle break? + +The tolerance threshold system (#105, medium priority) is the trigger mechanism — NPCs hit their limit and act. But #105 is medium priority and depends on the mood system (#102, also medium). The fuse AND the spark are both medium priority. + +**Emotional: 3/5** — Social triangles are INCREDIBLE when they fire. You're at the bar. Two NPCs who are usually friendly start arguing. Your monologue notes: "Something's changed between Tomas and Lira." You investigate. You find out Tomas discovered Lira's secret. And Lira's secret connects to the smuggling ring. THAT'S emergent drama. + +But that chain requires: triangle generation + tolerance thresholds + mood changes + behavior changes + the player being in the right place to observe + monologue interpretation. That's six systems, three of which are medium priority. For v0.1, I'm worried triangles exist on paper but never visibly fire. + +**What's missing:** A "triangle escalation event" system. When a triangle hits a threshold, it should generate an observable event — an argument, a door slam, a hushed conversation, someone drinking alone who's usually with friends. These are the TELLS. Without observable escalation events, triangles are pure backend. + +**Verdict:** Triangles need their escalation moments to be visible. Promote #105 (tolerance thresholds) or add an explicit "triangle event generation" ticket. + +--- + +## CONCEPT PROOF SCORECARD SUMMARY + +| Claim | Systemic | Emotional | Gap | +|-------|----------|-----------|-----| +| Asymmetric information | 4/5 | 3/5 | No first-playthrough mirror moment | +| Fog of perception | 5/5 | 4/5 | Sound through walls deprioritized (#128) | +| NPCs feel alive | 4/5 | 2/5 | No routine deviation detection system | +| Observation as mechanic | 3/5 | 3/5 | No observation event pipeline | +| Same world, different story | 4/5 | 5/5 | Need distinct daily rhythms per character | +| Social triangles | 3/5 | 3/5 | No observable escalation events | + +**Overall emotional average: 3.3/5.** That's a PROBLEM. The systems are mostly there (avg 3.8/5) but the player-facing emotional delivery is lagging behind. + +--- + +## TRACK 2: FUN & WOW FACTOR + +### FIRST 5 MINUTES: What does the player see? + +Okay. Game starts. You picked the smuggler. What happens? + +Looking at the tickets... I honestly can't tell you. And THAT'S a problem. + +Here's what I can reconstruct: +- Camera locks to your character (#116) in the station district (#153) +- You see a top-down view with fog of perception (#113) — the world beyond your vision is dark +- You're... standing somewhere? Your workplace? Your hab? + +**Where's the opening moment?** There's no "game start sequence" ticket. No ticket for where the character wakes up, what their first objective is, what the player sees in the first 30 seconds. Character build (#180-181) defines WHO they are. Station district layout (#153) defines WHERE they are. But nobody has defined WHEN — what's the first moment? + +**Ticket coverage for first 5 minutes:** +- Camera: #116 (critical) — yes +- Vision/fog: #110-113 (critical) — yes +- The station exists: #153 (critical) — yes +- NPCs walking around: #88 + #101 — yes +- Player can move: #73 (input), #83 (moving character proof) — yes +- Monologue fires: #119-122 — yes, but what does it SAY? +- Something to DO: ??? + +**THE HOOK IS MISSING.** The player starts the game and... walks around? Looks at NPCs? Waits for something to happen? There's no diegetic first objective. The smuggler should have a SHIFT to work. The detective should have a CASE FILE to review. Something that says "go HERE, do THIS" without being a tutorial popup. + +**Does the UI communicate asymmetric info without tutorial?** The fog of perception does heavy lifting here — the dark areas SCREAM "you can't see everything." The internal monologue (#119-122) is the diegetic tutorial (D-016 says so explicitly). But the monologue line pool (#120) needs to include FIRST-IMPRESSION lines for a character seeing their daily world. "Another shift at the hub. Same faces." That line does three things: establishes routine, tells you where to go, implies the world has patterns. That's tutorial without tutorial. + +**Rating: 2/5.** The systems exist for an opening. Nobody has designed the opening. We need a "first 5 minutes experience design" ticket. + +--- + +### THE "AHA" MOMENT + +**When does the player realize they're seeing a different world than the other character would?** + +Not in the first playthrough. Not directly. The asymmetry is INVISIBLE to a single perspective. You'd need to play both characters to fully get it. + +BUT — there are moments where you SENSE it. The smuggler hears that a detective has been asking questions at the bar. The detective hears that shipments have been rerouted. These are shadows of the other perspective bleeding through. + +**Is this in the ticket plan?** Kinda. Divergent starting knowledge (#182) means the characters know different things. The dialogue system (#168-174) means NPCs say different things to different characters. But the specific "other perspective bleeds through" moments need to be AUTHORED into the content packs (#190-192). This is a content design task for Mellanie and Paula, not a systems ticket. + +**When do they first catch an NPC doing something suspicious through observation?** + +THIS is the money moment. You're walking home from the bar. You see an NPC who should be at home at this hour, slipping into a side corridor. Your monologue: "That's Jax. He works morning shift at the hub. What's he doing out here at this hour?" + +For this to work you need: +1. NPC routines that create a "normal" pattern (#88, #101) +2. NPC SECRET behavior that breaks the pattern (part of smuggling ring template #186) +3. The player being in the right place at the right time (emergent, no ticket needed) +4. The monologue RECOGNIZING the deviation and commenting (#119, but not specifically designed for this) + +Items 1-3 are covered. Item 4 is the missing link I flagged in Track 1. Routine deviation → monologue comment. Without it, the player sees Jax in a corridor and thinks nothing of it. + +**When does the internal monologue first surprise them?** + +The monologue surprises the player when it reveals something the PLAYER didn't notice but the CHARACTER did. "She's nervous. Look at her hands." The player was watching an NPC conversation. The character noticed a tell the player missed. NOW the monologue is pulling its weight — it's a second pair of eyes with their own agenda. + +For the SMUGGLER, the surprise monologue is: "Better not mention the shipment around Kira. She's been asking too many questions." The character knows things the player is just learning about. + +For the DETECTIVE, it's: "Three people at the hub avoided eye contact with me. That's new." The character's training shows. + +These moments need to be in the monologue line pool (#120) and the character voice variation (#121). They're not infrastructure — they're CONTENT. And they're the moments that make the game feel alive. + +**Are these moments in the ticket plan, or hoping they emerge?** + +HOPING. The systems ALLOW these moments but nothing ENSURES them. The monologue event generation (#119) doesn't specify trigger conditions for routine deviations, social observations, or knowledge-reveals. The character voice variation (#121) is medium priority. + +**Rating: 3/5.** The "aha" CAN happen but it's not designed. It's emergent from systems that aren't yet wired together. + +--- + +### THE 30-MINUTE ARC + +**What's the shape of a play session?** + +Based on D-027: 30 minutes of daily life, then contamination activates. So: + +- Minutes 0-5: Orientation. Where am I? Who are these people? (See "First 5 minutes" above — this is underdesigned) +- Minutes 5-15: Routine. Go to work. Talk to coworkers. Visit the bar. Learn names and patterns. +- Minutes 15-25: Familiarity. You start recognizing faces. You know who sits where. You have OPINIONS about NPCs. Mundane triangles (#106-109) start showing texture — the bartender's rivalry with the logistics supervisor, the couple that fights every evening. +- Minutes 25-30: The itch. Something's off. An NPC breaks routine. A conversation stops when you walk in. Your monologue notes something you didn't consciously see. +- Minute 30+: Contamination. The storyteller activates. Now you're IN it. + +**Is daily life interesting enough to sustain 30 minutes?** + +THIS IS THE HARDEST QUESTION IN THE WHOLE PROJECT. + +I want to say yes, because D-023 (life-sim substrate) is correct — the daily life IS the game. But here's the truth: in a top-down view with placeholder art, "go to work and talk to coworkers" is interesting exactly as long as the DIALOGUE is interesting. And the dialogue system (#168-174) carries this ENTIRE 30 minutes. + +The four dialogue layers (D-028) are: +1. Access tiers — high priority (#169) +2. Relationship history — high priority (#170) +3. Trust-gated gossip — medium priority (#171) +4. Unprompted disclosure — medium priority (#172) + +Layers 3 and 4 are MEDIUM priority. But layers 3 and 4 are where the JUICE is. Access tiers tell you what you're allowed to hear. Relationship history makes NPCs remember you. But GOSSIP and UNPROMPTED DISCLOSURE are where you learn things you didn't ask for. Where NPCs volunteer information because they trust you. Where the bar comes alive with rumors and complaints and half-truths. + +If we ship with only layers 1-2, the dialogue is functional but flat. "Hello, smuggler." "Yes, I work at the hub." BORING. Layer 3 is where the bartender leans in and says "Don't tell anyone, but Jax has been staying late every night. I think he's got something going on." THAT'S the 30-minute sustainer. + +**Storyteller timing — is #162 (storyteller module activation) correctly ranked at LOW priority?** + +NO. NO NO NO. + +The storyteller doesn't need to be sophisticated for v0.1. It can be a TIMER. "After 30 minutes of game time, activate the smuggling ring drama module." That's it. That's the storyteller for v0.1. But WITHOUT it, the game has no arc. Daily life goes on forever. Nothing escalates. The player wanders around a station talking to people until they get bored and quit. + +#162 needs to be AT MINIMUM medium priority, probably high. The v0.1 storyteller can be dead simple — a trigger that fires contamination after a time threshold or player-engagement threshold. But it HAS to exist. The 30-minute arc demands it. + +**Rating: 3/5 if we promote gossip (#171) and storyteller (#162). 1/5 without them.** + +--- + +### MISSING WOW MOMENTS + +**Sound through walls:** + +The three-range model is specced (#124-128). But the WOW moment — pressing against a wall, hearing muffled voices, deciding to investigate — requires sound propagation physics (#128, LOW priority). + +Here's what I want: You're walking past a closed office. Through the wall, you hear raised voices. Your monologue: "Someone's angry in there." You can't see who. You can wait by the door, or you can note it and come back later. THAT moment converts fog-of-perception from a visual gimmick into an INFORMATION GAME. You're making decisions based on partial sensory data. That's the core loop. + +For v0.1, we don't need full physics simulation. We need: "if an NPC is making noise in an adjacent room, the player gets an audio indicator and a monologue line." That's achievable with #124 (sound events, high) and #126 (medium-range visual indicators, medium). Promote #126 or add a simplified "adjacent room sound" ticket. + +**Internal monologue contradicting reality:** + +The unreliable narrator mechanic (#123) is LOW priority. That's correct for FULL unreliable narration (the character actively deceives the player). But there's a lighter version that's ESSENTIAL: the character being WRONG. + +"Seems quiet. Safe to move." Then you round the corner and someone's there. That's not unreliable narration — it's the character's LIMITED information leading to an incorrect assessment. This should be a natural output of the monologue system responding to the character's current knowledge, not a special unreliable narrator mode. + +For v0.1, I want: monologue that reflects the character's CONFIDENT ASSESSMENT of incomplete information. The character doesn't know they're wrong. The player discovers they were wrong. That's achievable within #119-120 without #123. + +**NPC betrayal:** + +Is there a moment where an NPC the player trusted turns out to be lying? + +YES — this is the ENTIRE SMUGGLING RING. The smuggler trusts their coworkers. One of them is feeding information to someone. The detective trusts their informant. The informant has their own agenda. + +But this requires: the player forming trust FIRST (30-minute breathing room, dialogue layers 1-3), THEN discovering the betrayal (contamination activation, investigation). The emotional payload of betrayal is proportional to the investment. Rush the contamination and betrayal is "oh, that NPC I talked to twice was lying." Boring. Give it 30 minutes and betrayal is "Jax was my FRIEND. We had DRINKS together. And he was — this whole time?" THAT'S THE GAME. + +This reinforces: the 30-minute daily life runway is NON-NEGOTIABLE. D-027 got this right. Protect it. + +--- + +### THE BIG QUESTIONS + +**What's the single most exciting thing that can happen in the first 30 minutes?** + +For the SMUGGLER: You're having a normal day at the logistics hub. Moving cargo. Chatting with coworkers. Then you overhear your boss talking to someone you don't recognize. Your monologue: "I've never seen that person before. And why is the boss whispering?" You just stumbled onto the edge of something. You're not sure what. But your character's pulse is elevated and your monologue is SCREAMING at you to pay attention. You didn't go looking for trouble. Trouble walked past your field of vision. + +For the DETECTIVE: You're reviewing case files at your desk. You go to the bar to meet a contact. The contact doesn't show up. A stranger sits next to you and says something that makes your monologue fire: "That's oddly specific knowledge about port schedules for someone who claims to work in sanitation." You just met someone who knows more than they should. You didn't catch them doing something illegal. You caught them KNOWING something they shouldn't. + +BOTH of these moments are observation-driven, monologue-mediated, and emerge from systems not scripts. BOTH require the observation event pipeline I flagged in Track 1. + +**Are we front-loading the fun, or does the player need to grind through systems?** + +Right now? The fun is BACK-LOADED. The first 5 minutes are underdesigned (no opening moment ticket). The dialogue layers that make social interaction fun (#171-172 gossip and disclosure) are medium priority. The storyteller that creates arc (#162) is low priority. The sound-through-walls moment is deprioritized. The routine deviation detection doesn't exist. + +The INFRASTRUCTURE is front-loaded (engine, IPC, fog rendering — all critical). That's CORRECT for development. But we need to ensure that the FIRST systems we put content into are the ones that create player-facing moments. The first NPC that works should feel alive. The first monologue line should surprise someone. The first fog reveal should create tension. + +**Which tickets contribute to wow, and which are pure infrastructure?** + +**WOW tickets (player-facing moments):** +- #113 (fog rendering) — the first time the world goes dark around you +- #119-122 (monologue system) — the character's voice in your head +- #124-126 (sound events + close/medium audio) — hearing the world +- #174 (dialogue UI) — talking to NPCs +- #180-181 (smuggler + detective builds) — being SOMEONE +- #184-186 (workplace + bar + smuggling ring) — being SOMEWHERE +- #190-192 (content packs) — NPCs saying things that matter + +**INFRASTRUCTURE tickets (necessary but invisible):** +- #65-69 (Rust foundation) — nobody sees this +- #75-80 (IPC bridge) — nobody sees this +- #93-99 (simulation tiers) — nobody sees this (but it ENABLES everything) +- #138-142 (info boundaries) — nobody sees this directly +- #200-217 (testability) — nobody sees this + +**BOTH (wow requires infrastructure):** +- #110-112 (shadowcasting + vision) — infrastructure that IS the wow +- #88, #101 (routines) — infrastructure the player observes +- #106-109 (triangles) — infrastructure that creates drama + +**Is there a "demo moment" — something we could show someone in 2 minutes to sell the concept?** + +YES. And it's this: + +You're standing in a corridor. Fog obscures everything more than 20 tiles away. An NPC walks past. Your monologue: "That's Kira, from the hub. She usually works the morning shift." The NPC turns a corner and disappears into the fog. Your monologue: "It's 11pm. Why is she out?" + +30 seconds. One NPC. Fog. Monologue. Routine knowledge. Deviation. And the player's brain goes: "Should I follow her?" + +THAT IS THE GAME IN 30 SECONDS. + +And it requires: fog (#110-113), NPC routines (#88, #101), monologue (#119-120), routine deviation detection (NO TICKET), and character knowledge of NPC patterns (#182). + +--- + +## PRIORITY ADJUSTMENT RECOMMENDATIONS + +### PROMOTE (currently too low) + +| Ticket | Current | Recommended | Why | +|--------|---------|-------------|-----| +| #162 (Storyteller activation) | Low | High | Without it, no arc. Even a simple timer trigger is essential. | +| #171 (Trust-gated gossip) | Medium | High | This is where daily life becomes interesting. 30-min sustainer. | +| #172 (Unprompted disclosure) | Medium | High | NPCs volunteering info is a core wow moment. | +| #126 (Medium-range visual indicators) | Medium | High | Sound indicators at fog edge = player decisions. | +| #105 (Tolerance thresholds) | Medium | High | This is the trigger for triangle escalation events. | +| #121 (Character voice variation) | Medium | High | Smuggler and detective MUST sound different in monologue. | + +### NEW TICKETS NEEDED + +1. **"Routine deviation detection system"** — When an NPC breaks their established pattern, generate an observation event that feeds into the monologue system. This is the CORE DETECTIVE MECHANIC. Priority: CRITICAL. + +2. **"Observation event pipeline"** — Wire together: player witnesses NPC action → character interprets based on knowledge → monologue fires with appropriate certainty level. Priority: HIGH. + +3. **"First 5 minutes experience design"** — Define what each character sees, hears, and is directed to do in their first moments. Include opening monologue, diegetic first objective, and the environmental context. Priority: HIGH. + +4. **"Opening monologue and diegetic first objective"** — Content ticket for Mellanie: first 10-20 monologue lines for each character establishing who they are, where they are, and what they're doing today. Priority: HIGH. + +5. **"Triangle escalation events"** — When a social triangle hits a threshold, generate an observable event (argument, avoidance, emotional display) that the player can witness. Priority: HIGH. + +6. **"Demo scenario specification"** — Define a 2-minute demo sequence that showcases fog + NPC routine + monologue + routine deviation. For internal validation and external pitching. Priority: MEDIUM. + +--- + +## THE BOTTOM LINE + +The ticket plan builds a SIMULATION. 232 tickets of infrastructure, systems, content pipelines, and architecture. It's thorough. It's well-structured. It's impressive. + +But right now, the plan builds the MACHINE without designing the MOMENTS. The fog system exists but no one has designed the "holy shit, what's behind that corner" moment. The monologue system exists but no one has designed the "wait, my character noticed something I didn't" moment. The NPC routines exist but no one has designed the "they broke their routine and I SAW it" moment. + +The systems ALLOW these moments. Nothing ENSURES them. + +The single biggest risk to v0.1 is not technical. It's not scope. It's that we build every system correctly and the player sits there going "okay... now what?" + +**We need to design the moments, not just the systems.** + +The good news: the systems are RIGHT. Fog of perception, internal monologue, NPC routines, social triangles, asymmetric information — this is a PHENOMENAL foundation. The observation event pipeline and routine deviation detection I'm asking for are not new systems. They're the GLUE between existing systems. They're probably a combined 3-4 tickets of work. But they're the difference between a tech demo and a game that makes someone say "holy shit." + +And THAT — someone saying "holy shit" — is the success criterion that matters. + +--- + +*Written by Ozzie. From the gut.* diff --git a/docs/workshops/v01-gap-analysis/round1-paula.md b/docs/workshops/v01-gap-analysis/round1-paula.md new file mode 100644 index 000000000..9ae11c863 --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round1-paula.md @@ -0,0 +1,352 @@ +# Round 1 — Paula's Track 1 Analysis: Strength of Concept Proof + +**Agent:** Paula (Narrative & Political Depth) +**Track:** 1 — Strength of Concept Proof +**Date:** 2026-02-11 + +--- + +## Overview + +Let me complicate the question the workshop is asking. The workshop asks: "Does the ticket catalog deliver on each claim?" But what SUSTAINS a concept proof across 30 minutes of play isn't whether systems exist — it's whether those systems produce *meaning*. A mechanically flawless information boundary that generates no narrative tension has proved nothing. A triangle system that creates structural conflicts but no emotional stakes has proved nothing. The honest truth is that several of these claims have strong mechanical foundations but weak narrative connective tissue. The tickets build the skeleton. The question is whether the skeleton can hold flesh. + +I'm evaluating each claim on three dimensions: +1. **Mechanical coverage** — Do the tickets build the system? +2. **Narrative delivery** — Does the system produce story? +3. **Emotional resonance** — Does the story make the player feel something? + +--- + +## Claim 1: Asymmetric Information Is the Core Mechanic + +**Tickets:** #138-142 (info boundaries), #182-183 (divergent knowledge/relationships) + +### Mechanical Coverage: STRONG + +The information boundary system (#138-142) is well-architected. Component-level access control (#139), observer-based entity filtering (#140), knowledge-based gating (#141), and NPC information boundaries (#142) form a complete pipeline. This isn't fog-of-war bolted on — it's structural. The ObserverSnapshot (D-020) means the client literally cannot display what the character doesn't know. Good. + +Divergent starting knowledge (#182) and divergent relationships (#183) create the initial conditions for the smuggler and detective to see the world differently. The smuggler knows criminals and workplace gossip; the detective knows institutional info and case files. Same NPCs, inverted trust maps. + +### Narrative Delivery: MODERATE — with a significant gap + +Here's where I need to complicate things. The tickets deliver *data asymmetry* — the smuggler sees different component data than the detective. But data asymmetry is not the same as *narrative asymmetry*. The question is: does the smuggler experience a different STORY, or just see different data fields on the same NPCs? + +**What's present:** The smuggler knows the dock worker's name, their role in the smuggling operation, their debts. The detective sees "dock worker, routine shift pattern, no flags." That's a good starting divergence. + +**What's missing:** There's no ticket that translates information asymmetry into *interpretive asymmetry*. The internal monologue system (#119-123) is the bridge here, but it's not explicitly connected to the information boundary system. The smuggler looking at the dock worker should trigger monologue like *"Kael's running late again. If the boss notices..."* while the detective sees the same person and gets *"Dock worker. On schedule. Nothing unusual."* That interpretive layer — where the same visual stimulus produces different character thoughts — is where information asymmetry becomes narrative asymmetry. + +**Gap:** No ticket explicitly connects #138-142 (information boundaries) to #119-122 (monologue system) through character knowledge. The monologue tickets describe event triggers and line pools, but don't specify that monologue generation should query the character's knowledge state to produce character-specific interpretations of observed entities and events. + +### Emotional Resonance: WEAK — needs design work + +Information asymmetry creates tension only when the player *feels* the weight of knowing or not-knowing. The smuggler who knows their colleague is smuggling contraband should feel the *dread* of being close to someone who could expose them. The detective who doesn't know should feel the *frustration* of seeing normalcy where their instincts say something is wrong. + +These are emotional states that emerge from the monologue system reflecting on information boundaries, not from the boundaries themselves. The monologue needs to do emotional work — not just inform, but *interpret with feeling*. + +**Specific gap:** #182 (divergent starting knowledge) is described as "inverted information sets" — a mechanical framing. It should also define *emotional starting positions*. The smuggler's knowledge of the criminal network comes with anxiety, loyalty pressure, and complicity. The detective's ignorance comes with institutional confidence and the nagging sense that this district is too quiet. Starting knowledge isn't just data — it's emotional context. + +### Risk Rating: MEDIUM + +The mechanical foundation is solid. The narrative bridge (monologue as interpreter of information asymmetry) is designed but not explicitly wired. The emotional layer is underspecified. The claim will be *mechanically* provable but may feel flat without deliberate work on the interpretive and emotional dimensions. + +### Minimum Bar for v0.1 + +The smuggler and detective, looking at the same NPC, should produce different monologue lines that reveal different knowledge AND different emotional relationships to that knowledge. If the monologue says the same thing with different facts, we've failed. If it says different things with different feelings, we've proved the claim. + +--- + +## Claim 2: Fog of Perception Creates Tension + +**Tickets:** #110-113 (shadowcasting -> fog rendering) + +### Mechanical Coverage: STRONG + +Shadowcasting (#110), vision cone (#111), observer visibility query (#112), and fog rendering (#113) are all critical priority and well-specified. The vision cone with forward/peripheral/behind sectors means the player literally has a blind spot behind them. The fog returns on departure, so previously explored areas become uncertain. Solid. + +### Narrative Delivery: MODERATE + +The workshop question is precise: is *fogless-information* (what you know but can't see) captured in the narrative layer? This is the most interesting question in the entire analysis. + +**What fog does mechanically:** You can't see behind walls, around corners, or behind you. NPCs in fog are invisible. + +**What fog doesn't capture:** Your character KNOWS things about what's in the fog. The smuggler knows their colleague is in the warehouse right now because they share a shift schedule. The detective knows the suspect lives in apartment 3B because of case files. This knowledge-in-fog is where tension lives — you *know* something is happening beyond your vision, but you can't verify it. + +**The monologue bridge:** Ticket #119 (monologue event generation) includes "NPC proximity" as a trigger, but doesn't explicitly address the case where a *known* NPC is beyond perception range. The monologue should fire not just when you see something, but when you *don't* see something you expected. *"Kael should be at the dock by now. Haven't seen him."* That absence-awareness is where fog creates narrative tension, not just visual occlusion. + +**Gap:** No ticket covers "expected-but-absent" detection — the system comparing the character's knowledge of NPC routines against observed reality and flagging discrepancies. This is the bridge between the information boundary system (#138-142) and the fog system (#110-113) that creates the narrative experience of "something's wrong but I can't see what." + +### Emotional Resonance: MODERATE + +Fog inherently creates anxiety — you can't see what's there. But fog-of-perception is more specific: you can't see what you *know* is there. The smuggler who knows the contraband handoff happens in the next room, but can't see through the wall, feels complicity and dread. The detective who suspects activity behind that door, but has no legal authority to enter, feels frustration and moral tension. + +These emotional states are character-specific responses to fog, mediated by knowledge and identity. The monologue system can deliver them, but the tickets don't explicitly call for knowledge-aware fog responses. + +### Risk Rating: MEDIUM-LOW + +The mechanical system is strong. The narrative gap (knowledge-aware absence detection) is designable and not architecturally complex — it's a query against the character's known-NPC-routine data filtered against current perception. The emotional layer needs monologue lines authored specifically for "I know something is happening that I can't see" situations. + +### Minimum Bar for v0.1 + +At least one moment per playthrough where the monologue comments on the *absence* of something the character expected to see, creating tension about what's happening beyond the fog. The smuggler should think about a colleague who isn't where they should be. The detective should notice a suspect's routine has changed without being able to see why. + +--- + +## Claim 3: NPCs Feel Alive Without Player Attention + +**Tickets:** #88 (daily routines), #93-99 (simulation tiers), #101 (routine execution) + +### Mechanical Coverage: STRONG + +The simulation tier system (#93-99) is well-designed. Background NPCs tick through state machines (schedule, mood, relationships, job) at 1/game-minute. Active NPCs get full behavior. The tier transition system means NPCs are always *somewhere* doing *something* even when the player can't see them. Routine execution (#101) drives schedule-based movement. + +### Narrative Delivery: MODERATE — with a critical distinction + +But what SUSTAINS the feeling of alive NPCs across hours of play is not whether they move on schedules — it's whether the *consequences* of their off-screen life are visible when the player returns. + +**What the tickets deliver:** NPCs move between locations on schedule, change mood over time, and have relationships that drift. When you return to the bar after a day at work, the bartender is there because their schedule says they should be. + +**What the tickets don't explicitly deliver:** Evidence of off-screen life that the player can *discover*. The bartender should have had a bad day while you were at work — their mood shifted, they argued with a regular, and when you arrive, their greeting is different. The background relationship dynamics ticket (#103) is marked MEDIUM priority and described as "relationship values change over time, decay, reinforcement" — but this is the mechanism that makes NPCs feel like they lived while you were away. + +**Gap 1: Relationship dynamics (#103) should be HIGH priority for v0.1.** Without it, NPCs have routines but no *interpersonal continuity*. They move around the map, but their relationships don't evolve. This makes them automata, not people. + +**Gap 2: No ticket covers "off-screen event narration."** When the player returns to a social site after absence, there should be discoverable evidence of what happened. The monologue might note *"Something's different here. The regulars are avoiding the corner table."* An NPC might reference an event: *"You missed it — Sario and the boss had it out yesterday."* These discovery moments are what make off-screen life legible to the player. + +### Emotional Resonance: WEAK without relationship dynamics + +If NPCs only have routines, they feel like clockwork. If their relationships evolve off-screen and the player discovers the consequences, they feel like people with lives. The emotional payoff is: "the world didn't wait for me, and now I have to deal with what happened while I was gone." + +**Specific concern:** Ticket #198 (Criterion 3: Emotional NPC attachment) is a validation ticket, not a design ticket. It says "after playthrough, player names an NPC they felt conflicted about." But no ticket is responsible for *producing* that emotional attachment. Emotional attachment emerges from repeated interactions where the NPC's responses reflect history, mood, and relationship state — which requires #103 (relationship dynamics), #170 (relationship history dialogue), and #172 (unprompted disclosure) all working together. Three of those four are MEDIUM priority. + +### Risk Rating: MEDIUM-HIGH + +The mechanical simulation is solid. The narrative delivery mechanisms (relationship dynamics, off-screen event narration, unprompted disclosure) are either medium priority or missing. The emotional resonance target (Criterion 3) has no explicit design path to delivery. This is the claim most at risk of being mechanically present but narratively empty. + +### Minimum Bar for v0.1 + +After leaving a social site and returning, at least one NPC's behavior or dialogue must reflect something that changed while the player was away. And the player must be able to discover what changed through conversation or observation, not through a notification. + +--- + +## Claim 4: Observation Is a Mechanic, Not a Cutscene + +**Tickets:** #115 (NPC vision), #124-128 (sound model), #119-122 (internal monologue) + +### Mechanical Coverage: MODERATE + +The observe->notice->follow->discover chain requires: +- **Observe:** Vision system (#110-113) + NPC routines (#88, #101) = you can watch NPCs do things +- **Notice:** Tell system (#90) + monologue (#119-122) = something flags as unusual +- **Follow:** Player movement + NPC pathing = you can physically tail someone +- **Discover:** Information boundaries (#138-142) + dialogue layers (#168-174) = you learn something new + +Each link in the chain has ticket coverage. The question is whether the chain is *connected*. + +### Narrative Delivery: THE CRITICAL QUESTION + +The workshop asks: "Where does the MEANING come from?" This is the right question, and the honest answer is: meaning comes from the *narrative interpretation* that sits between each mechanical link. + +**Observe -> Notice:** The player sees an NPC. What makes them *notice*? Not just the tell system mechanically flagging behavior. The monologue must contextualize: *"That's the third time this week Kael has gone to the loading bay after hours. His shift ended an hour ago."* The monologue transforms raw perception into suspicion. Without it, the player sees an NPC walking somewhere and has no reason to care. + +**Notice -> Follow:** The player decides to follow. This is a *player choice* — no ticket can deliver it. But the game must make the choice feel *available*. The monologue can plant the seed: *"I could follow him. Or I could mind my own business."* This is where D-016's "diegetic tutorial" function becomes load-bearing. The monologue suggests actions without commanding them. + +**Follow -> Discover:** The player follows and sees something. The discovery must be *legible*. If the smuggler follows Kael to a secret meeting, the scene needs to be readable through the fog system — partial information, overheard fragments, visible but unidentifiable figures. Then the monologue interprets: *"That's... who is that? Kael never mentioned knowing anyone in cargo processing."* + +**Gap:** The tell system (#90) is described as "behavioral indicators" and "trait-driven behavior modifiers" — but there's no ticket specifying what tells LOOK LIKE in the top-down renderer. How does the player visually distinguish "NPC acting normally" from "NPC acting suspiciously"? In a 3D game, you'd see body language. In a top-down game with placeholder art, tells need to be communicated through: +- Movement pattern changes (NPC looks around before entering a room — needs animation states or movement hesitation) +- Routine deviations (NPC goes somewhere unusual — needs the "expected-but-absent" system I flagged in Claim 2) +- Monologue interpretation (character notices and comments — needs monologue wired to tell system) + +The first two need visual/behavioral expression tickets. The third needs explicit monologue-tell integration. + +### Emotional Resonance: HIGH POTENTIAL — if the chain connects + +The observe->notice->follow->discover chain, when it works, is the single most satisfying experience in detective fiction. The player who pieces together a conspiracy from their own observations — without quest markers, without explicit instruction — will feel the pride of genuine deduction. This is the game's highest-potential moment. + +But it fails catastrophically if any link breaks. If observation doesn't produce noticeable tells, the player never starts the chain. If the monologue doesn't interpret what they see, they don't understand why it matters. If following doesn't lead to legible discovery, the payoff fizzles. + +### Risk Rating: MEDIUM-HIGH + +The individual systems exist. The chain connections are underspecified. The visual expression of tells in top-down view is unaddressed. The monologue's role as narrative interpreter of the observation chain is implicit but not explicitly designed into the ticket connections. + +### Minimum Bar for v0.1 + +One complete observe->notice->follow->discover chain that works without scripted triggers. The player watches an NPC, notices a behavioral anomaly through tells and/or monologue, follows by choice, and discovers information that changes their understanding of a situation. This chain must emerge from systems, as Criterion 4 (#199) requires. + +--- + +## Claim 5: Same World, Different Story + +**Tickets:** #179-183 (character builds), #196-199 (success criteria) + +### Mechanical Coverage: MODERATE + +Character definition (#179), smuggler build (#180), detective build (#181), divergent knowledge (#182), and divergent relationships (#183) establish the starting conditions. But all five tickets are marked "NEEDS DESIGN DISCUSSION" — they're placeholders, not specifications. + +### Narrative Delivery: THE MAKE-OR-BREAK CLAIM + +This is the claim I care most about, because it's where narrative depth either emerges or doesn't. + +**Mechanical divergence is easy:** The smuggler has insider access; the detective has authority access. Different dialogue pools, different information boundaries, different starting knowledge. The tickets cover this. + +**Narrative divergence is hard:** The smuggler and detective need to experience different *stories*, not just different *access levels*. Let me be specific about what this means: + +**The Smuggler's Story:** Daily life is the cover. Going to work at the logistics hub IS the smuggling operation. The tension isn't "go investigate" — it's "maintain normalcy while the walls close in." The smuggler's relationships with criminal NPCs are loaded with loyalty, fear, and complicity. When the detective starts sniffing around (as a background event the smuggler notices), the smuggler's story is about *protection* — protecting colleagues, protecting the operation, protecting themselves. The emotional core is: how far will you go to protect people you care about who are doing illegal things? + +**The Detective's Story:** Daily life is the investigation. Walking the district, talking to people, observing routines. The tension is "I know something is wrong but I can't prove it." The detective's relationships with institutional NPCs (the precinct, the informant network) are loaded with obligation and political pressure. When evidence points toward people the detective has started to like (bar regulars, workplace acquaintances), the detective's story is about *betrayal* — the discovery that normalcy was a mask. The emotional core is: what do you do when the truth threatens the community you've come to value? + +**Gap:** The tickets describe starting conditions (knowledge, relationships, access). They don't describe *narrative arcs*. The smuggler's story has an arc: safety -> pressure -> crisis -> choice. The detective's story has an arc: confidence -> suspicion -> evidence -> confrontation. These arcs need to be designed, not just hoped for. + +**Specific missing elements:** +1. **Smuggler-specific tension escalation:** No ticket describes how the smuggling ring's situation deteriorates over time, creating pressure on the smuggler. Does the operation get sloppy? Does a new rival appear? Does someone in the ring consider betraying the others? This pressure is what drives the smuggler's story forward. +2. **Detective-specific investigation progression:** No ticket describes how the detective accumulates evidence and builds a case. Is there a case file system? How does the detective know they're making progress? Investigation needs a progression mechanic beyond "discover more facts." +3. **Convergence point:** What happens when the smuggler's protective instincts and the detective's investigation collide? This doesn't need to be a scripted scene — but the game needs mechanical hooks for "the investigation reaches someone the smuggler cares about" and "the smuggler's colleague gets arrested/questioned." These are the emotional climaxes that make both stories meaningful. + +### Emotional Resonance: HIGH POTENTIAL — if arcs are designed + +The smuggler protecting friends from justice and the detective pursuing justice that threatens a community are mirror images of the same moral question. This is genuinely powerful narrative design. But it requires: +- The smuggler to feel *loyalty* (relationship depth, shared history, trust) +- The detective to feel *doubt* (moral complexity, community attachment, institutional pressure) +- Both to face *consequences* (actions that ripple through the social fabric) + +None of these emotional states are ticket-specified. They're assumed outcomes of systems that exist for other reasons. + +### Risk Rating: HIGH + +This is the weakest claim in the ticket plan despite being the most important. The mechanical foundations (information boundaries, dialogue layers, character builds) exist. The narrative arcs that would make two playthroughs feel like different *stories* rather than different *access levels* are not designed. The emotional divergence — smuggler-as-protector vs. detective-as-pursuer — is powerful but entirely implicit. + +### Minimum Bar for v0.1 + +After playing both characters, a player should be able to describe each as having a *different emotional journey*, not just different starting information. "The smuggler was about protecting people; the detective was about uncovering truth" — not "the smuggler knew different things than the detective." + +--- + +## Claim 6: Social Triangles Create Emergent Drama + +**Tickets:** #106-109 (triangle generation), #175-176 (entanglement ratio) + +### Mechanical Coverage: MODERATE + +Triangle definition schema (#106), intra-template generation (#107), cross-template generation (#108), and validation (#109) cover the structural creation of triangles. The 30/50/20 entanglement ratio (#175) ensures most triangles are mundane, creating the noise floor that investigation requires. + +### Narrative Delivery: MODERATE — with critical gaps + +The triangle model I proposed in Round 17 is sound: 3 NPCs with conflicting interests as the atomic unit of intrigue. But the tickets as specified describe *triangle creation*, not *triangle dynamics*. + +**What the tickets deliver:** Generate three NPCs with conflicting interests. Validate that the conflict is viable. Place them in social sites. + +**What the tickets don't deliver:** + +**1. Triangle escalation.** Triangles are static at generation time — A owes B, B is jealous of C, C needs A's help. But triangles need to *evolve*. Over time, A's debt worsens. B's jealousy becomes resentment. C's need becomes desperation. Without escalation mechanics, triangles are *situations*, not *stories*. Stories need arcs. + +**Missing ticket:** "Triangle escalation system" — periodic state updates that push triangle tensions toward breaking points. Connected to the tolerance threshold system (#105, medium priority) but not explicitly linked. When any NPC in a triangle approaches their tolerance threshold, the triangle should enter a new phase with different behavioral tells and dialogue options. + +**2. Triangle consequences.** When a triangle breaks (tolerance exceeded, secret exposed, betrayal occurs), what happens? The NPC who breaks doesn't just change a relationship score — they ACT. They confront someone. They leave. They seek help from the player. They seek help from someone else, pulling that person into the triangle's aftermath. + +**Missing ticket:** "Triangle resolution and aftermath" — behavioral responses when triangle tensions resolve (through breaking, intervention, or time). This is where triangles produce the emergent stories the claim promises. + +**3. Player involvement in triangles.** The player enters an existing triangle as an external force. Their actions — helping one NPC, pressuring another, revealing information — shift the triangle's dynamics. But no ticket describes how player actions modify triangle state. The dialogue system (#168-174) allows the player to interact with individual NPCs, but doesn't describe how those interactions ripple through the triangle. + +**Missing ticket:** "Player-triangle interaction effects" — how player actions toward one triangle member affect the others' attitudes, behaviors, and dialogue. This is the mechanism by which the player *plays* the social game. + +**4. Triangle visibility.** How does the player *discover* that a triangle exists? They don't see a "triangle" — they see individual NPCs behaving in ways that suggest connections. The bartender complains about the landlord. The landlord asks about the bartender. The player connects the dots. This discovery process needs: +- Gossip lines that reference triangle members (#171, trust-gated gossip — medium priority) +- Behavioral tells when triangle members interact with each other (#90, tell system) +- Monologue interpretation when the player observes triangle dynamics (#119-122) + +These systems exist but aren't explicitly connected to triangle generation. + +### Emotional Resonance: HIGH POTENTIAL — if triangles have arcs + +A static triangle is a puzzle: figure out who wants what, play them against each other. A dynamic triangle is a drama: watch tensions build, see people hurt each other, feel the weight of intervening (or not). The emotional payoff of triangles is the feeling of being complicit in someone else's story — you made a choice, and it affected people who didn't ask for your involvement. + +The mundane triangles (50% of the population per D-029) are where this emotional payoff matters most. A neighbor dispute that the player could resolve or inflame. A workplace rivalry where the player's promotion depends on who wins. These aren't intrigue — they're *life*. And they're what creates the attachment that makes intrigue stakes meaningful. + +### Risk Rating: MEDIUM-HIGH + +Triangle creation is well-specified. Triangle dynamics (escalation, consequences, player interaction, resolution) are not. The claim promises "emergent drama" — but drama requires arcs, not just initial conditions. The tickets build triangle starting states; the narrative systems that make triangles evolve and resolve are missing or medium priority. + +### Minimum Bar for v0.1 + +At least one triangle that the player discovers through observation and dialogue, where their involvement (or non-involvement) produces a visible consequence affecting at least two NPCs' behavior. The triangle should feel like a story that happened because of the player's choices, not a static relationship the player noticed. + +--- + +## Missing Claims: What the Game Should Also Prove + +### Missing Claim A: Consequences Ripple Through the Social Fabric + +The game makes a strong implicit claim that actions have consequences — but no ticket explicitly covers a **consequence propagation system**. When the player helps one NPC, their ally should warm toward the player AND their rival should cool. When the player reveals a secret, the exposed NPC's relationships should shift, and those shifts should cascade. + +The relationship dynamics ticket (#103) covers dyadic changes. But cascading consequences — where an action toward A affects A's relationship with B, which affects B's behavior toward C — are the social-fabric simulation that makes the world feel interconnected. + +**Suggested ticket:** "Consequence propagation — social ripple effects" (high priority). When a player action modifies a relationship, propagate effects through the relationship graph with decay. First-order effects are strong and immediate. Second-order effects are weaker and delayed. Third-order effects are ambient mood shifts. + +### Missing Claim B: Moral Complexity Is Systemic, Not Scripted + +The game should prove that there are no clean answers. The smuggler isn't evil — they're protecting friends. The detective isn't good — they're serving an institution with its own agendas. This moral ambiguity needs to be systemic, not just written into backstory. + +**What's needed:** NPCs in the smuggling ring should have sympathetic motivations discoverable through relationship building and trust-gated disclosure. The detective's institution should have questionable practices discoverable through investigation. The game should resist categorizing anyone as villain or hero. + +**What's missing:** No ticket describes "institutional critique" content for the detective's faction — the case files that reveal overreach, the colleague who bends rules, the informant who feels exploited. Without this, the detective's institutional access feels like a superpower, not a complicated bargain. + +### Missing Claim C: Character Growth Through Experience + +The v0.1 slice is 30 minutes, but even in that window, the character should *change*. Not level up — change in how they understand their world. The smuggler who discovers a colleague is in deeper trouble than they thought. The detective who realizes the district isn't what it seemed. + +The monologue system can express this growth: early monologue is confident and routine; late monologue is uncertain and questioning. But no ticket describes **monologue evolution over a play session** — the progression from baseline character voice to experience-modified character voice. + +**Suggested ticket:** "Monologue state progression" (medium priority). Track significant discoveries and relationship changes; modify monologue tone and content to reflect accumulated experience. Early: *"Same old shift."* Late: *"Nothing about this place is what I thought it was."* + +--- + +## Summary Scorecard + +| Claim | Mechanical | Narrative | Emotional | Overall Risk | Minimum Bar | +|-------|-----------|-----------|-----------|-------------|-------------| +| **1. Asymmetric info** | Strong | Moderate | Weak | MEDIUM | Different monologue = different feelings, not just different facts | +| **2. Fog = tension** | Strong | Moderate | Moderate | MEDIUM-LOW | Monologue on absence: "I expected X and don't see it" | +| **3. NPCs alive** | Strong | Moderate | Weak | MEDIUM-HIGH | Discoverable evidence of off-screen change on return | +| **4. Observation mechanic** | Moderate | Moderate | High potential | MEDIUM-HIGH | One unscripted observe->notice->follow->discover chain | +| **5. Same world, different story** | Moderate | Weak | High potential | **HIGH** | Different emotional journeys, not just different access | +| **6. Triangles = drama** | Moderate | Moderate | High potential | MEDIUM-HIGH | One triangle with player-affected consequences | + +### The Pattern + +The ticket catalog builds strong mechanical foundations but underspecifies the narrative connective tissue between systems. The gaps are not in what systems exist — they're in how systems *talk to each other* to produce narrative meaning. The monologue system is the critical bridge between mechanical state and narrative experience, and it needs to be more explicitly wired to information boundaries, fog, observation, and relationship dynamics. + +### Priority Adjustments I'd Recommend + +| Ticket | Current | Recommended | Reason | +|--------|---------|-------------|--------| +| #103 Relationship dynamics | Medium | **High** | Required for Claim 3 (NPCs alive) and Claim 6 (triangle dynamics) | +| #105 Tolerance threshold triggers | Medium | **High** | Required for Claim 6 (triangle escalation) and Claim 4 (observation chain) | +| #171 Trust-gated gossip | Medium | **High** | Required for triangle discovery and progressive revelation | +| #172 Unprompted disclosure | Medium | **High** | Required for NPC-initiated narrative moments and off-screen event narration | +| #123 Unreliable narrator | Low | Medium | Contributes to emotional depth but not critical for v0.1 proof | +| #162 Storyteller module activation | Low | Medium | Without storyteller, the 30-min runway has no escalation curve | + +### New Tickets I'd Propose + +1. **"Knowledge-aware monologue integration"** (high) — Connect monologue generation (#119) to information boundaries (#138-142) so that character knowledge produces character-specific interpretive commentary on observed entities and events. + +2. **"Absence detection system"** (high) — Compare character's known NPC routine data against observed reality. Flag discrepancies. Feed into monologue system. "I expected to see X and don't." This is the bridge between fog and narrative tension. + +3. **"Triangle escalation and resolution"** (high) — Periodic state updates that push triangle tensions toward breaking points. Behavioral changes when triangles enter crisis. Consequences when triangles resolve. Connected to tolerance thresholds (#105). + +4. **"Player-action social propagation"** (high) — When player actions modify a relationship, propagate effects through the relationship graph. First-order strong and immediate, second-order weaker and delayed. + +5. **"Tell visual/behavioral expression"** (high) — Define how NPC tells manifest in the top-down renderer. Movement hesitation, routine deviation markers, interaction changes. Without this, the observation chain has no visual starting point. + +6. **"Character arc progression — smuggler and detective"** (high) — Design the narrative arcs for both characters: what emotional journey each follows, what escalation triggers drive the arc forward, what choice points emerge from systems. Not scripted events — designed pressure curves that systems can deliver. + +7. **"Monologue tone progression"** (medium) — Track cumulative discoveries and relationship changes; modify monologue tone from confident/routine to uncertain/questioning as the play session evolves. + +--- + +## Final Assessment + +The ticket catalog builds a *simulation*. What it doesn't yet fully build is a *narrative experience*. The gap isn't architectural — the systems are right. The gap is in the connective tissue: how information boundaries produce interpretive monologue, how fog produces absence-awareness, how triangles produce arcs, how the smuggler and detective produce different *emotional journeys*. + +The honest truth is that the strongest claim (Claim 1: asymmetric information) and the weakest claim (Claim 5: different story) are two ends of the same problem. We have excellent mechanical infrastructure for information asymmetry. We have underspecified design for what that asymmetry *means* narratively. The v0.1 vertical slice will prove whether we can bridge that gap — but only if we deliberately design the bridge, not hope it emerges. + +The monologue system is the MVP of narrative delivery. It's the cheapest system (it's text), the most flexible system (contextual, character-specific, mood-responsive), and the most load-bearing system (it translates mechanical state into emotional experience). Every gap I've identified routes through the monologue system. Investing in deep monologue integration with every other system is the single highest-ROI narrative decision for v0.1. diff --git a/docs/workshops/v01-gap-analysis/round1-tyre.md b/docs/workshops/v01-gap-analysis/round1-tyre.md new file mode 100644 index 000000000..dd6c1e3ed --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round1-tyre.md @@ -0,0 +1,750 @@ +# Workshop Round 1 — Tyre (Technical Architect) + +**Tracks:** 3 (Things We May Have Forgotten) + 4 (Testability Deep-Dive) +**Date:** 2026-02-11 + +--- + +## TRACK 3: Things We May Have Forgotten — Technical Gap Analysis + +*cracks knuckles* + +Let me be honest about what's missing. I've gone through the 232 tickets systematically, cross-referenced with confirmed decisions, and found genuine gaps. I'll categorize each as **HARD BLOCKER** (v0.1 cannot ship without this), **SOFT BLOCKER** (v0.1 works but feels broken without it), or **NICE-TO-HAVE** (defer safely). + +--- + +### 3.1 Pathfinding — HARD BLOCKER + +**Status:** No ticket exists. Zero coverage. + +NPCs need to navigate the station district. Ticket #101 (Routine execution system) says "schedule-driven NPC movement, location transitions at scheduled times" but there is no system to actually move an NPC from point A to point B. #83 (Moving character proof) handles player movement via direct input, but NPCs need autonomous navigation. + +**What's needed:** +- A* grid pathfinding on the tile map. For a 150x150 tile map, this is well within performance budget. +- Wall/obstacle avoidance from the tile collision data. +- Path caching — NPCs following daily routines walk the same paths repeatedly. Cache hot paths. +- Door/gate traversal — the station district has a gate corridor (#157). NPCs need to know how to use doors. + +**Implementation in Rust/bevy_ecs:** There's no built-in pathfinding in bevy_ecs. Options: +1. **`pathfinding` crate** (crates.io) — mature, has A* and Dijkstra, works on arbitrary graphs. ~10 lines to integrate with tile grid. **Recommended.** +2. **Custom A*** — it's a well-known algorithm, easy to implement. But why reinvent it? +3. **Navigation mesh** — overkill for a tile-based top-down game. Save this for if we ever do free-form movement. + +**Effort estimate:** 1-2 stories. One for the pathfinding system itself, one for integrating it with NPC routine execution (#101). + +**New tickets needed:** +- `[story] Tile-based A* pathfinding system` (high priority, blocks #101) +- `[story] NPC path following and movement` (high priority, blocks #101) + +--- + +### 3.2 Collision Detection — HARD BLOCKER + +**Status:** No ticket exists. Zero coverage. + +Both player movement (#83) and NPC movement (#101) need collision detection. Without it, entities walk through walls. + +**What's needed:** +- Tile-based collision map — walls, furniture, objects marked as solid tiles. This comes from the tile map data. +- Entity-tile collision check before movement — "can I move to tile X,Y?" query. +- Entity-entity collision (optional for v0.1) — preventing NPCs from stacking on the same tile. Low priority but feels weird without it. + +**Architecture note:** Collision lives in the Rust simulation, not the Godot client. The simulation is authoritative (D-010). The client just renders where entities are. + +**What this is NOT:** +- Physics simulation. No rigid bodies, no forces, no momentum. This is tile-based "is the target tile walkable?" checks. +- Complex collision shapes. Entities occupy tiles. Tiles are solid or not. + +**Effort estimate:** 1 story. Tile collision map + movement validation. Small but load-bearing. + +**New tickets needed:** +- `[story] Tile collision system` (critical priority, blocks #83 and #101) + +--- + +### 3.3 Z-levels — NICE-TO-HAVE (for v0.1) + +**Status:** #114 (Multi-z-level LOS) is low priority. Correct. + +**Assessment:** The station district (#153) *could* be designed as a single z-level for v0.1. D-014 says "2-3 z-levels" but that's the full spec — the vertical slice can work on one floor. + +**Recommendation:** Design the station district as single-level for v0.1. Add a second floor as a stretch goal. The chunk-based map architecture (D-012) already supports z-levels in the data model — we just don't need to render or pathfind across them yet. + +**Risk if deferred:** None for v0.1. The data model supports it. Adding z-levels later is an extension, not a rewrite. + +**No new tickets needed.** #114 stays low priority. The station district layout (#153) should note "single z-level for v0.1." + +--- + +### 3.4 Time System — HARD BLOCKER + +**Status:** Q-009 is open. No ticket beyond #25 (Time system, medium priority, backlog). + +This is a genuine blocker. Daily routines (#88) say "time-based transitions" but there is no time system defined. Every NPC behavior system depends on knowing what time it is. + +**What Q-009 needs to decide (minimum for v0.1):** +1. **Tick-to-game-time mapping.** If the simulation runs at 10-20 tps (D-026), how many ticks = 1 game-minute? Proposal: 1 game-minute = 10 ticks at 10 tps (= 1 real second). A 30-minute play session = ~12-18 game-hours. This gives a full "day" of NPC routines in one play session. +2. **Day structure.** Morning/afternoon/evening/night phases that drive routine transitions. NPCs go to work in the morning, to the bar in the evening. Simple phase system. +3. **Time display.** Player needs to know what time it is (insert HUD element). Diegetic — it's on their neural insert. +4. **Pause.** Can the player pause? Probably yes for v0.1 (single-player). Simulation freezes, UI stays responsive. + +**What we do NOT need for v0.1:** +- Deep time (years, decades) — v0.1 is one play session +- Day/night lighting changes — placeholder art doesn't need this +- Seasonal cycles +- Time zone differences between locations + +**Effort estimate:** 1 story for the time system, 1 story for the time display. Promotes #25 from medium to high priority. + +**New tickets needed:** +- Promote #25 to high priority (blocks #88) +- `[story] Game clock and day-phase system` (high priority, blocks #88) +- `[story] Time display on insert HUD` (medium priority) + +--- + +### 3.5 Audio Engine — SOFT BLOCKER + +**Status:** Sound propagation is specced (#124-128) but there's no basic audio foundation ticket. + +**The gap:** Godot 4 has a built-in AudioServer with AudioStreamPlayer2D for positional audio. This is the client-side playback engine — we don't need to build one. But there's no ticket for: +- Setting up the audio bus layout in the Godot project +- Loading and managing sound assets +- Connecting sound events from the ObserverSnapshot to AudioStreamPlayer2D instances +- Basic ambient/environmental audio (background hum of the station) + +Tickets #124-128 jump straight to sophisticated sound propagation. The bridge between "server generates SoundEvent" and "client plays audio" is assumed but not specified. + +**What's needed for v0.1:** +- Client-side audio manager that receives sound events from snapshot and plays them +- A small library of placeholder sounds (footsteps, door, conversation murmur, alert) +- Spatial audio positioning relative to camera + +**Effort estimate:** 1 story. This is Godot built-in functionality with a thin integration layer. + +**New tickets needed:** +- `[story] Client audio manager and spatial playback` (high priority, supports #124-125) + +--- + +### 3.6 Asset Pipeline — SOFT BLOCKER + +**Status:** #133 (Placeholder art pipeline) exists but lacks specifics. + +**What #133 needs to specify (or a companion design ticket):** +- **Tile size:** 32x32 pixels is the sweet spot for top-down. 16x16 is too small for readable detail. 48x48 is feasible but unusual. **Recommendation: 32x32.** +- **Sprite dimensions:** Character sprites. 32x48 (taller than wide) is standard for top-down characters standing on 32x32 tiles. +- **Animation frames:** For v0.1 placeholder art? Minimal: idle (1 frame), walk (4 frames per direction), interact (2 frames). That's ~18 frames per character × 4 directions = ~72 frames. For colored boxes with labels? 1-2 frames per state. +- **Tileset format:** Godot TileSet resource. Atlas-based or individual tiles? Atlas is better for performance. +- **Naming conventions:** `npc_smuggler_walk_north_01.png` or sprite sheet coordinates? +- **Color coding for placeholder art:** Since D-014 says "colored boxes with labels" — which colors mean what? Walls = dark gray, floor = light gray, NPC = colored by role, player = distinct color, interactable objects = highlighted. + +**Recommendation:** This is a design discussion for Araminta + Stig, but needs a ticket. The art direction question (Q-003) doesn't need full resolution for v0.1 — we just need placeholder conventions. + +**Effort estimate:** Half a story to define the spec, which then unblocks #133. + +**New tickets needed:** +- `[task] Define placeholder art specification` (high priority, blocks #133) + +--- + +### 3.7 Save/Load — SOFT BLOCKER + +**Status:** Complete gap. No ticket anywhere. + +**Let me be honest about what this means technically:** + +Serializing a bevy_ecs World is non-trivial. Options: + +1. **bevy_reflect + bevy_scene:** Bevy has a reflection system that can serialize entities and components. It works but requires all components to derive `Reflect`. This is the "Bevy way" but couples us to Bevy's serialization format. + +2. **Custom serialization:** Define a `SaveState` struct that captures the game state we care about (entity positions, NPC states, relationship data, time, knowledge graphs, quest states). Serialize with serde + bincode or MessagePack. Deserialize by reconstructing the ECS world from SaveState. + +3. **Snapshot-based:** The simulation already produces ObserverSnapshots. A save is just a full-world snapshot (not observer-filtered). This leverages existing serialization infrastructure. + +**Recommendation for v0.1:** Option 2 (custom serialization). We control the save format, it's independent of bevy_ecs internals, and it doubles as the foundation for the state-save tier in D-026 (which already needs "frozen serialized structs ~1-2KB each" for state-saved NPCs). + +**What's needed:** +- `SaveState` data structure capturing full game state +- Serialize to file (serde + bincode or MessagePack) +- Deserialize and reconstruct ECS world +- "Save and quit" / "Load and resume" flow in the client + +**Effort estimate:** 2-3 stories. This is real work, but it shares architecture with the simulation tier serialization (#96 - State serialization system). They should be designed together. + +**New tickets needed:** +- `[story] Save state data model and serialization` (high priority, shares design with #96) +- `[story] Save/load game flow - client integration` (medium priority) + +**Architecture note:** #96 (State serialization system) already covers serializing NPC state for tier transitions. Save/load is "serialize everything, not just one NPC." The same serialization infrastructure serves both purposes. These should share implementation. + +--- + +### 3.8 Session Management — SOFT BLOCKER + +**Status:** No ticket. + +**What happens when the player launches the game?** +1. Main menu (new game / load game / settings / quit) +2. New game → character selection (smuggler or detective) +3. World generation (station district instantiation, NPC generation, template placement) +4. Game starts — player character placed in starting location + +**What happens when the player stops playing?** +1. Pause → save and quit +2. Quit without saving → warning prompt +3. Return → load from save → resume + +**For v0.1, this can be minimal:** +- No main menu (launch directly into game) +- Character selection via command-line argument or simple dialog +- Auto-save on quit +- Auto-load on start if save exists + +**Effort estimate:** 1 story for the basic session flow. Low complexity. + +**New tickets needed:** +- `[story] Game session management - start/save/resume flow` (medium priority) + +--- + +### 3.9 Game Over / Failure States — NICE-TO-HAVE (for v0.1) + +**Status:** No ticket. But also — does v0.1 need failure states? + +**D-027 success criteria focus on:** 30-min daily life runway, different playthroughs, emotional NPC attachment, emergent observation. None of these require game-over conditions. + +**D-008 says** death = information loss via memory cell backup. But for v0.1: is there combat? The smuggling ring template is about deception and social dynamics, not combat. The detective investigates; they don't get killed (in v0.1). + +**Recommendation:** Defer game-over/failure states to post-v0.1. The vertical slice is about proving the information asymmetry concept, not about win/lose conditions. If the 30-minute session ends, it ends — that's success criterion #1. + +**What we MIGHT want for v0.1:** +- "Session complete" screen after the 30-min runway +- Basic stats: "You observed X, discovered Y, talked to Z NPCs" +- Comparison between smuggler and detective perspectives + +**Effort estimate if included:** 1 story. Low priority. + +**No new tickets needed** unless the team wants a session-end summary screen. + +--- + +### 3.10 Content Volume — FEASIBLE BUT TIGHT + +**Status:** This is a scope question, not a missing ticket. + +**The math:** +- 3 social site templates: workplace (4-8 NPCs), bar (4-8 NPCs), smuggling ring (4-8 NPCs) +- Single-ownership model (D-025) means some NPCs are shared via reference links +- Realistic count: ~20-25 unique NPCs with ~5-8 shared across templates +- Each NPC has 10 axes (D-024): Want, Secret, Relationships ×3, Tolerance, Routine, Information, Contentment + 3 supporting +- Entanglement ratio (D-029): 30% flat / 50% mundane triangles / 20% intrigue + +**For 20-25 NPCs with the 30/50/20 split:** +- 5-6 flat NPCs (routine + greeting only) +- 10-13 mundane triangle NPCs (neighbor disputes, workplace rivalries) +- 4-5 intrigue-entangled NPCs (smuggling ring connections) + +**Is this achievable?** +- **Data modeling:** Yes. 25 NPCs × 10 axes = 250 data points. Well within authoring budget. +- **Content authoring (Mellanie):** 3 templates × 165-210 lines (D-028) = ~495-630 authored lines before generation expansion. That's a significant but bounded writing task. The line previewer CLI (#193) must be ready before Mellanie starts — it's her authoring tool. +- **Runtime simulation:** 25 NPCs in active tier at 10-20 tps? Trivially easy. D-026 budgets for 30-80 active NPCs. We're well under ceiling. +- **Triangle generation:** D-024 says 2 triangles per template minimum + 1 cross-template = 7 triangles minimum across 3 templates. Each triangle = 3 NPCs with conflicting interests. 7 triangles involving ~20 NPCs is tight but workable — NPCs participate in multiple triangles. + +**Verdict:** Feasible. The bottleneck is content authoring time, not technical capability. The line previewer CLI (#193) is correctly marked critical — it's the tool that makes the writing volume manageable. + +**Risk:** If Mellanie's content authoring takes longer than expected, reduce the mundane triangle NPCs first. The flat NPCs and intrigue NPCs are load-bearing; the mundane triangles are the adjustable dial. + +--- + +### 3.11 Additional Gaps Discovered + +#### 3.11.1 Player Interaction System — HARD BLOCKER + +**Status:** Partially covered but fragmented. + +#73 (Input capture) maps keys to semantic actions. #230 (PlayerInput structure) includes `Interact` as an action type. But there's no ticket for **what happens when the player interacts**: +- Walk up to NPC → press Interact → what system handles this? → dialogue system (#168-174) +- Walk up to door → press Interact → door opens? No door system ticket. +- Walk up to object → press Interact → examine? No examination system ticket. +- Walk up to terminal → press Interact → access information? No terminal interaction ticket. + +**The gap:** There's no interaction dispatcher — the system that takes "player pressed Interact near entity X" and routes to the appropriate subsystem (dialogue, object examination, door, terminal). + +**New tickets needed:** +- `[story] Interaction dispatcher system` (high priority) — takes Interact input + proximity + target entity type → routes to appropriate handler + +#### 3.11.2 NPC Movement System — HARD BLOCKER + +**Status:** Implied but not explicitly ticketed. + +#101 (Routine execution system) implies NPCs move between locations. #68 (Basic entity components) gives entities Position and Facing. But there's no explicit "NPC movement system" that updates position per tick along a path. + +This is distinct from pathfinding (finding the route) — this is the actual per-tick position update, animation state, facing direction change. + +**This is part of the pathfinding gap (3.1)** but worth calling out: the movement system is the thing that runs every tick, consuming path waypoints and updating Position. Pathfinding generates the path; movement follows it. + +**New tickets needed:** +- Already covered by the pathfinding tickets proposed in 3.1. The "NPC path following and movement" story covers this. + +#### 3.11.3 Player Journal / Knowledge Tracking UI — SOFT BLOCKER + +**Status:** No ticket. + +#89 (Information inventory) tracks what the player character *knows* in the simulation. But there's no client-side UI for the player to review what they've learned. The insert/minimap (#148-152) handles spatial navigation. Where does the player see their accumulated knowledge? + +For v0.1 this could be minimal: a simple list of "things you know" accessible via a key press. But without it, the player has to remember everything themselves, which undermines the insert concept (D-013). + +**New tickets needed:** +- `[story] Knowledge/journal display - client` (medium priority) — shows information inventory contents in insert UI + +--- + +### Track 3 Summary: New Tickets Needed + +| Priority | Title | Blocks | Effort | +|----------|-------|--------|--------| +| **Critical** | Tile collision system | #83, #101 | S | +| **High** | Tile-based A* pathfinding system | #101 | M | +| **High** | NPC path following and movement | #101 | M | +| **High** | Game clock and day-phase system (promote/replace #25) | #88 | M | +| **High** | Interaction dispatcher system | #168 (dialogue) | M | +| **High** | Client audio manager and spatial playback | #124, #125 | S | +| **High** | Define placeholder art specification | #133 | XS | +| **High** | Save state data model and serialization | shared with #96 | L | +| **Medium** | Save/load game flow - client integration | — | M | +| **Medium** | Game session management - start/save/resume | — | S | +| **Medium** | Time display on insert HUD | — | S | +| **Medium** | Knowledge/journal display - client | — | M | + +**S = Small (1-3 days), M = Medium (3-5 days), L = Large (5-10 days), XS = Extra Small (< 1 day)** + +**Hard blockers (v0.1 cannot ship):** Collision, pathfinding, NPC movement, time system, interaction dispatcher +**Soft blockers (v0.1 feels broken):** Audio manager, asset spec, save/load, session management +**Nice-to-have:** Knowledge journal, game-over states, z-levels + +--- + +## TRACK 4: Testability Deep-Dive + +### 4.1 Rust: Testing Strategy Recommendation — HYBRID + +**Recommendation: `#[cfg(test)]` for unit tests + external integration tests.** + +Here's why a hybrid approach is right: + +#### Unit tests with `#[cfg(test)]` — inside modules + +**For:** Testing internal algorithms where the public API is too coarse. + +Examples: +- Shadowcasting algorithm internals (#110) — does ray N correctly identify wall tile at (x,y)? +- Pathfinding heuristic (#new) — does A* correctly navigate around an L-shaped wall? +- Perception query filtering (#112) — does the vision cone correctly exclude tiles behind the observer? +- Time-to-tick conversion (#new) — does 14:30 game-time map to the correct tick number? + +These are pure functions or small systems that have well-defined inputs and outputs. They live right next to the code they test. They run with `cargo test` instantly. + +```rust +// simulation/src/perception/shadowcast.rs + +pub fn compute_visible_tiles(origin: IVec2, range: i32, is_opaque: impl Fn(IVec2) -> bool) -> HashSet { + // ... shadowcasting implementation +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn wall_blocks_vision() { + let opaque = |pos: IVec2| pos == IVec2::new(2, 0); // wall at (2,0) + let visible = compute_visible_tiles(IVec2::ZERO, 5, opaque); + assert!(visible.contains(&IVec2::new(1, 0))); // before wall + assert!(!visible.contains(&IVec2::new(3, 0))); // behind wall + } +} +``` + +#### Integration tests — external `tests/` directory + +**For:** Testing the simulation as a consumer (the Godot client) would use it. + +These exercise the full tick loop: create a World, add entities, run N ticks, assert on resulting state. + +```rust +// simulation/tests/tick_integration.rs + +use simulation::{SimulationBuilder, PlayerInput, ActionType}; + +#[test] +fn player_move_updates_position() { + let mut sim = SimulationBuilder::new() + .with_test_map(10, 10) + .with_player_at(5, 5) + .build(); + + sim.queue_input(PlayerInput::new(ActionType::Move(Direction::North))); + sim.tick(); + + let snapshot = sim.observer_snapshot(sim.player_entity()); + assert_eq!(snapshot.player_position, IVec2::new(5, 4)); +} +``` + +These tests prove the public API works. They're how Dudley (server dev) knows the simulation is correct from the client's perspective. They exercise system scheduling, component interactions, and the observer query pipeline. + +#### Why not external test crate only? + +Because some internal algorithms need testing at a granularity the public API can't reach. The shadowcasting algorithm might have 15 edge cases (corners, T-junctions, diagonal walls) that need individual tests. Testing each through the full simulation tick loop is possible but wasteful and fragile. + +#### Why not `#[cfg(test)]` only? + +Because the most important tests are the ones that exercise the real system — full tick, real scheduling, actual observer queries. Those MUST use the public API to catch integration bugs. + +#### Workspace structure: + +``` +simulation/ + Cargo.toml # [lib] + [[test]] targets + src/ + lib.rs # Public API: SimulationBuilder, tick(), observer_snapshot() + perception/ + shadowcast.rs # Has #[cfg(test)] mod tests + vision_cone.rs # Has #[cfg(test)] mod tests + navigation/ + pathfinding.rs # Has #[cfg(test)] mod tests + ecs/ + components.rs + systems.rs + tests/ + tick_integration.rs # Integration: full tick loop + observer_snapshot.rs # Integration: observer queries + npc_behavior.rs # Integration: NPC routines + pathfinding + information_boundary.rs # Integration: info filtering +``` + +--- + +### 4.2 Godot: Framework Recommendation — GUT + +**Recommendation: GUT (Godot Unit Testing) framework.** + +#### Why GUT over gdUnit4: + +| Criterion | GUT | gdUnit4 | +|-----------|-----|---------| +| Maturity | 8+ years, battle-tested | Newer, less proven | +| Documentation | Comprehensive wiki | Growing but thinner | +| Community | Larger, more Stack Overflow answers | Smaller | +| GDScript-native | Yes | Yes | +| Headless support | Yes (`--headless`) | Yes but less tested | +| Signal testing | Good | Better (more fluent API) | +| Test doubles | Built-in | Built-in | +| Claude Code compatibility | Better documented patterns | Less AI training data | +| Complexity | Simpler, less magic | More features, more complex | + +gdUnit4 has a more modern API (fluent assertions, better signal testing) but GUT's maturity and simplicity win for a project where the Godot client is intentionally thin. We're not testing complex GDScript logic — we're testing that the client correctly renders snapshots and captures input. + +#### Can Claude Code run `godot --headless`? + +**Yes, with constraints.** + +Godot 4 supports `--headless` mode which runs without a display server (no X11/Wayland needed). This is how CI/CD pipelines run Godot tests. + +```bash +godot --headless --script res://addons/gut/gut_cmdline.gd \ + -gdir=res://test/ -gprefix=test_ -gsuffix=.gd -gexit +``` + +**Requirements:** +1. Godot 4 binary must be installed and on PATH (or referenced by absolute path) +2. The project must be initialized (`.godot/` directory with imported resources) +3. First run may need `godot --headless --import` to build the import cache +4. No GPU required for headless mode + +**Potential issue:** If the Godot binary isn't installed in the dev environment, headless tests can't run. This should be a documented setup prerequisite. + +**When do we need Godot tests?** + +Honestly? Not urgently. The client is a "dumb renderer" (D-020). For v0.1: +- Input mapping (key → semantic action) — simple enough to verify manually +- Snapshot rendering (ObserverSnapshot → sprites) — visual verification, hard to unit test meaningfully +- UI elements — not complex enough to warrant test infrastructure yet + +**Recommendation:** Set up GUT in Sprint 1 (#205) but write minimal tests initially. The Rust side is where testing pays off. Godot tests become valuable when we have: +- Complex UI state (dialogue system #174) +- Input simulation for playtest automation (#207) +- Rendering verification for fog overlay correctness (#208) + +--- + +### 4.3 Integration Testing: Real IPC, Not Mocks + +**Recommendation: Test against the real subprocess/IPC bridge.** + +The subprocess/IPC architecture (D-020) means the simulation is a standalone binary. Integration tests should exercise the actual protocol: + +``` +Test runner (Rust or shell script) + → Spawns simulation binary as subprocess + → Connects via IPC (local socket) + → Sends PlayerInput messages (MessagePack) + → Receives ObserverSnapshot responses + → Asserts on snapshot contents + → Kills subprocess on teardown +``` + +#### Why real IPC, not mocks? + +1. **The IPC IS the production path.** Mocking it tests mock behavior. We need to know the real serialization/deserialization works, the real socket connection works, the real subprocess lifecycle works. + +2. **The simulation binary already exists as a test target.** We're building a standalone binary (#65, #66, #67). Running it in a test is literally what #81 (E2E connection test) describes. These aren't extra test infrastructure — they're the actual integration stories. + +3. **Mock maintenance cost.** A mock IPC would need to be updated every time the protocol changes. The real binary is always in sync with itself. + +#### When mocks ARE appropriate: + +- **Client-side unit tests** that test GDScript logic without needing a running simulation. The client can have a `MockBridge` that returns hardcoded snapshots for testing UI rendering and input handling in isolation. +- **Protocol format tests** that verify MessagePack serialization independently of the full simulation. + +#### Integration test structure: + +``` +test/ + integration/ + test_connection.rs # Spawn binary, connect, verify handshake + test_movement.rs # Send move input, verify position change in snapshot + test_perception.rs # Verify observer filtering (entity behind wall not in snapshot) + test_npc_routine.rs # Advance time, verify NPC position changes + fixtures/ + test_map_small.bin # Pre-generated 10x10 map for fast tests + test_npcs_minimal.json # 3 NPCs with known configurations +``` + +--- + +### 4.4 Test Output Format for Agent Consumption + +**Recommendation: `cargo-nextest` for Rust, GUT console for Godot.** + +#### Rust: cargo-nextest + +Standard `cargo test` output is human-readable but not structured. `cargo-nextest` provides: +- **JUnit XML output** — universally parseable, works with any CI system +- **Per-test timing** — identifies slow tests +- **Parallel execution** — faster test runs on multi-core +- **Retry support** — flaky test detection +- **Structured JSON output** — ideal for agent consumption + +```bash +cargo nextest run --message-format libtest-json 2>&1 +# or for JUnit XML: +cargo nextest run --profile ci # with .config/nextest.toml configured for junit output +``` + +For Claude Code agent consumption, the key format is: **test name, pass/fail, duration, failure message if any.** `cargo-nextest`'s default output provides all of this clearly. + +If nextest is too heavy for initial setup, standard `cargo test` with `--format json` (nightly) or even default output works. The test names and PASS/FAIL lines are parseable enough. + +#### Godot: GUT console output + +GUT outputs test results to Godot's console output. In headless mode, this goes to stdout. Format: + +``` +[PASS] test_snapshot_renders_entities +[FAIL] test_fog_overlay_covers_unseen - Expected fog at (3,4) but found visible +``` + +Simple, parseable, sufficient. + +#### Summary format recommendation: + +``` +test/run-rust → cargo nextest run (or cargo test) → stdout + optional JUnit XML +test/run-godot → godot --headless + GUT → stdout +test/run-ipc → custom integration runner → stdout + exit code +test/run-all → runs all three sequentially → combined stdout +``` + +--- + +### 4.5 Test Pollution Boundaries — Where's the Line? + +**Core rule: No test-only code paths in production code that change behavior.** + +This means: +- **NO** `#[cfg(test)]` blocks in production modules that alter execution paths +- **NO** mock injection points or "if testing" branches +- **NO** making fields `pub` just so tests can access them +- **NO** `pub(crate)` solely for test visibility + +**What IS acceptable:** + +1. **`#[cfg(test)] mod tests` at the bottom of a source file.** This is standard Rust practice. The test module lives in the same file but compiles away in release builds. No production code is changed. + +2. **Public API boundaries as test seams.** The `SimulationBuilder` pattern gives tests clean construction without test-specific hooks: + ```rust + // This is the production API, not a test hack + pub struct SimulationBuilder { + map_config: MapConfig, + npc_configs: Vec, + } + ``` + Tests use the same builder that the real game uses, just with different configs (small map, few NPCs). + +3. **Trait-based abstraction for external dependencies.** The `SimBridge` trait (D-020) is a production abstraction — it exists because we need LocalBridge and NetworkBridge. Tests can create a `TestBridge` that records inputs and replays snapshots. This isn't test pollution; it's the natural consequence of good architecture. + +4. **ECS component queries as natural seams.** bevy_ecs is inherently testable — create a World, add components, run systems, query results. No mocking framework needed. No test hooks in production code. The ECS architecture IS the test infrastructure. + +5. **Deterministic simulation with controlled inputs.** If the simulation is deterministic (D-010 principle 4), then feeding the same inputs produces the same outputs. Tests set up initial state, feed known inputs, assert on outputs. No randomness to mock out. + +**Where bevy_ecs makes this easy:** + +```rust +#[test] +fn npc_follows_routine() { + let mut world = World::new(); + + // Set up test state directly — no mock injection needed + let npc = world.spawn(( + Position(IVec2::new(5, 5)), + DailyRoutine { /* morning: go to work at (10, 10) */ }, + GameTime { hour: 8, minute: 0 }, + )).id(); + + // Run the routine execution system + let mut schedule = Schedule::default(); + schedule.add_systems(routine_execution_system); + schedule.run(&mut world); + + // Assert NPC is moving toward work + let pos = world.get::(npc).unwrap(); + // ... assert path was generated toward (10, 10) +} +``` + +No mocking. No dependency injection. No test hooks. Just create the world state you want and run systems on it. This is bevy_ecs's killer feature for testability. + +**Production code constraints (#217) summary:** +1. No conditional compilation that changes production behavior +2. No `pub` visibility escalation for tests +3. No test-specific parameters on production functions +4. Public API is the test surface — if something can't be tested through the public API, the API boundary is wrong +5. ECS World setup is the test fixture — not mock objects + +--- + +### 4.6 Test Runners as Bash Commands + +**Yes. Following the `db/connectors/sqlite-*` pattern.** + +``` +test/ + run-rust # #!/bin/bash — cd simulation && cargo nextest run "$@" + run-godot # #!/bin/bash — godot --headless --script ... + run-ipc # #!/bin/bash — builds sim binary, runs integration tests + run-all # #!/bin/bash — runs all three, reports summary +``` + +Each script: +- Is whitelistable for Claude Code agents +- Returns exit code 0 on success, non-zero on failure +- Outputs human-readable AND agent-parseable results to stdout +- Accepts arguments to filter tests (e.g., `test/run-rust -- test_shadowcast`) +- Runs without interactive input (no prompts, no `--interactive` flags) + +**Additional utility scripts:** + +``` +test/ + run-rust-watch # cargo watch + nextest for TDD loop + run-coverage # cargo llvm-cov (if we want coverage metrics) + run-bench # cargo bench for performance regression +``` + +--- + +### 4.7 Ticket #214 Refinement — Decisions Needed + +#214 (Refinement discussion) blocks #215-217. Here are the decisions I'm proposing based on this analysis: + +#### Decision 1: Rust test organization = Hybrid +- `#[cfg(test)]` for unit tests inside modules +- `tests/` directory for integration tests +- Both run via `cargo test` / `cargo nextest run` +- **Status: Ready for team confirmation** + +#### Decision 2: Godot test framework = GUT +- Install GUT as addon in client project +- Headless execution via `godot --headless` +- Minimal initial tests, expand with UI complexity +- **Status: Ready for team confirmation** + +#### Decision 3: Integration tests = Real IPC +- Spawn actual simulation binary in tests +- Test the real MessagePack protocol over real sockets +- Mock bridge only for client-side unit tests +- **Status: Ready for team confirmation** + +#### Decision 4: Production code constraints +- No test-only code in production modules +- Public API is the test surface +- ECS World setup replaces mock injection +- Trait boundaries (`SimBridge`) are natural test seams +- **Status: Ready for team confirmation** + +#### Decision 5: Test runner tooling +- `cargo-nextest` for Rust (install as dev dependency) +- GUT for Godot +- Bash wrapper scripts in `test/` directory +- **Status: Ready for team confirmation** + +#### Decision 6: Test output format +- Rust: nextest default output + optional JUnit XML +- Godot: GUT console output +- Integration: stdout + exit code +- **Status: Ready for team confirmation** + +#### Still needs discussion: +- **Deterministic replay system (#201):** How do we record and replay input sequences? This needs a design session. It's high value for regression testing but not a blocker for initial test infrastructure. +- **Performance benchmarks (#204):** What are our performance baselines? Need to define: tick budget (ms per tick), entity count targets, serialization throughput. Not urgent for v0.1 with 25 NPCs. +- **Flaky test policy:** How do we handle non-deterministic test failures? With deterministic simulation, there shouldn't be many. But integration tests involving subprocess lifecycle could be flaky. Policy: flaky tests are bugs, not tolerated. + +--- + +## Cross-Track Dependencies + +| Track 3 Gap | Track 4 Impact | +|-------------|---------------| +| Collision system | Needs unit tests for tile walkability checks | +| Pathfinding | Needs unit tests for A* algorithm + integration tests for NPC routing | +| Time system | Needs unit tests for tick-time conversion + integration tests for routine triggering | +| Interaction dispatcher | Needs integration tests for interact → dialogue flow | +| Save/load | Needs integration tests for serialize → deserialize roundtrip | + +--- + +## Priority Summary + +### Immediate v0.1 blockers requiring new tickets: +1. **Tile collision system** — nothing moves correctly without this +2. **Pathfinding + NPC movement** — NPCs can't follow routines without this +3. **Time system (promote Q-009 / #25)** — routines depend on knowing what time it is +4. **Interaction dispatcher** — player can't talk to NPCs without this + +### Soft blockers needing attention: +5. **Audio manager** — sound events need a client-side player +6. **Placeholder art spec** — #133 needs specifics before implementation +7. **Save/load** — required for any real play session, shares design with #96 + +### Testability priorities: +8. **Confirm the 6 decisions above** — unblocks #215, #216, #217 +9. **Set up `cargo nextest` and test/run-* scripts** — first developer experience +10. **Write first integration test alongside #81 (E2E connection test)** — test infra grows with features + +--- + +*That's my technical assessment. The good news: none of these gaps are architecturally surprising. They're all "systems we assumed existed but nobody ticketed." The collision + pathfinding + time system trio is the most critical — nothing works without them. The testability decisions are clear-cut; I'm confident in the hybrid approach.* + +*— TYRE* diff --git a/docs/workshops/v01-gap-analysis/round2-gestalt.md b/docs/workshops/v01-gap-analysis/round2-gestalt.md new file mode 100644 index 000000000..0cf0bbaa3 --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round2-gestalt.md @@ -0,0 +1,429 @@ +# Round 2 Workshop Response: Gestalt (Systems Design) + +**Agent:** Gestalt (Systems Design & Fun Factor) +**Date:** 2026-02-11 +**Round:** 2 — Cross-pollination and synthesis + +--- + +## 1. Unified Observation System: Merging Ozzie's Pipeline with My Verbs + +*Let me break down what this actually means mechanically.* + +Ozzie and I independently identified two halves of the same system. Ozzie identified the **passive** half (observation event pipeline + routine deviation detection). I identified the **active** half (observation verbs: follow, examine, wait, eavesdrop). Paula identified a third dimension — **absence detection** (the monologue noting what ISN'T there). These aren't three systems. They're three layers of ONE system. + +### The Unified Observation System: Three Layers + +``` +Layer 1: PERCEPTION (already ticketed) + #110-113 (vision), #124-128 (sound), #115 (NPC vision) + → Raw sensory data: "entity X is at position Y doing action Z" + → This layer is COMPLETE in the ticket plan + +Layer 2: INTERPRETATION (Ozzie's pipeline + Paula's absence detection) + → Character's knowledge state + perceived data → Observation Events + → "That's unusual" / "That's expected" / "Where's the person I expected?" + → Feeds into monologue (#119-122) as trigger events + → THIS IS THE MISSING SPINE + +Layer 3: ACTION (my observation verbs) + → Player responds to interpretation with active verbs + → FOLLOW, EXAMINE, WAIT — each changes the information flow + → THIS IS THE MISSING PLAYER AGENCY +``` + +### Layer 2: The Observation Event Generator (The Spine) + +This is the unified version of Ozzie's "observation event pipeline" + "routine deviation detection" + Paula's "absence detection system" + my "NPC off-routine behavior." It's ONE system with multiple trigger types. + +**Input:** ObserverSnapshot (what the character perceives this tick) + +**Processing:** Compare perceived state against character knowledge: + +| Trigger type | Comparison | Example | Source proposal | +|-------------|------------|---------|----------------| +| **Routine deviation** | NPC observed location/action vs known routine pattern | "Kael works mornings but he's at the docks at midnight" | Ozzie: routine deviation detection | +| **Absence detection** | Expected NPC at known location vs not observed | "Kira should be at the bar by now. Haven't seen her" | Paula: absence detection system | +| **Social anomaly** | NPC interaction observed vs known relationship state | "Since when are Tomas and Lira speaking? They hate each other" | Gestalt: NPC off-routine behavior | +| **New information** | Observed entity/action not in knowledge base | "I've never seen that person before" | Implicit in existing tickets | +| **Contradiction** | Observed state contradicts known information | "She said she was going home but she's heading toward the cargo bay" | Paula: knowledge-aware monologue | + +**Output:** `ObservationEvent` containing: +- `entity_id` — who/what was observed +- `trigger_type` — which comparison fired +- `deviation_score` — how unusual (0.0 = expected, 1.0 = shocking) +- `uncertainty` — how confident the interpretation is (distance, lighting, partial view) +- `character_context` — what the character knows that makes this notable + +**Downstream consumer:** Monologue event generation (#119). The ObservationEvent becomes a monologue trigger, with the character voice (#121) and knowledge state determining the actual line. + +**Critical design point from Gore:** The observation event generator must be CHARACTER-SPECIFIC. The smuggler and detective, looking at the same NPC doing the same thing, should generate DIFFERENT observation events because they have different knowledge bases. The smuggler seeing Kael at the docks at midnight thinks: "He's early for the drop." The detective seeing the same thing thinks: "Why is a morning-shift worker here at midnight?" Same perception. Different interpretation. THAT is the mechanical expression of "who you are determines what is real." + +### Layer 3: Active Observation Verbs (Minimal Set) + +From my Round 1 list of 7 verbs, here's the v0.1 minimal set with integration into the observation pipeline: + +**FOLLOW (High priority — required by D-027 criterion 4)** + +| Aspect | Design | +|--------|--------| +| Activation | Player designates a target NPC (interact while facing them at distance) | +| Mechanic | Game tracks distance and LOS to target. NPC suspicion increases if you're too close too long (#115 NPC vision feeds this) | +| Observation pipeline effect | While following, observation events fire at HIGHER frequency — the character is actively watching. Monologue shifts to tracking mode | +| Success condition | Target reaches destination, player observes what they do there | +| Failure condition | Target enters fog (lost), target notices you (suspicion), you lose patience (time) | +| Minimal implementation | Tag player with `Following(entity_id)`. System generates monologue on target movement. If target exits player vision, fire "lost target" monologue. If target's NPC vision (#115) detects player following for >N ticks, fire "detected" event | + +**EXAMINE (High priority — investigation requires this)** + +| Aspect | Design | +|--------|--------| +| Activation | Player uses interact on entity/object at close range | +| Mechanic | Returns detail information filtered through character knowledge (#138-142 info boundaries) | +| Observation pipeline effect | Generates detailed ObservationEvent with low uncertainty | +| Character specificity | Smuggler examining cargo manifest: "Standard shipment log. But these quantities are off — someone's skimming." Detective examining same manifest: "Shipping records. Some entries have irregular timestamps." SAME OBJECT, DIFFERENT DETAILS based on knowledge state | +| Minimal implementation | `Examinable` component on entities/objects. Interaction triggers info boundary query. Result feeds monologue as a detailed observation event | + +**INTERACT (Critical — general-purpose verb, my "player interaction framework")** + +| Aspect | Design | +|--------|--------| +| Activation | Player presses interact near a target entity | +| Mechanic | Interaction dispatcher routes to appropriate subsystem based on target type | +| Routing table | NPC → dialogue system (#168-174). Object → examine system. Door → open/close. Terminal → information access | +| Minimal implementation | `Interactable` component with `InteractionType` enum. Dispatcher matches type to handler. This is Tyre's "interaction dispatcher" — same system, same solution | + +**DEFERRED VERBS:** WAIT/STAKE OUT (medium — can simulate by just standing and observing), EAVESDROP (emergent from sound system + positioning — not a separate verb), PICK UP (low for v0.1). + +### Consolidated Ticket Proposal for the Unified Observation System + +| # | Title | Priority | Absorbs | Type | +|---|-------|----------|---------|------| +| NEW-1 | Observation event generator | **Critical** | Ozzie's "observation event pipeline," "routine deviation detection"; Paula's "absence detection," "knowledge-aware monologue integration"; my "NPC off-routine behavior" | Story | +| NEW-2 | Player interaction system + dispatcher | **Critical** | My "player interaction framework"; Tyre's "interaction dispatcher" | Story | +| NEW-3 | Follow mechanic | High | — | Story | +| NEW-4 | Examine mechanic | High | — | Story | +| NEW-5 | Wait/time-skip mechanic | Medium | — | Story | + +**That's 4 original proposals from me, 3 from Ozzie, and 2 from Paula, consolidated into 5 tickets.** The observation event generator is the big merge — it absorbs 5-6 independently proposed tickets into one coherent system. + +### Dependency Chain + +``` +Perception pipeline (#110-113, #124-128) + └→ Observation event generator (NEW-1) + ├→ Requires: Character knowledge state (#89, #138-142) + ├→ Requires: NPC routine data (#88, #101) + ├→ Feeds: Monologue event generation (#119) + └→ Feeds: Active verbs (NEW-3, NEW-4) + +Player input (#73, #230) + └→ Interaction dispatcher (NEW-2) + ├→ Routes to: Dialogue system (#168-174) + ├→ Routes to: Examine mechanic (NEW-4) + └→ Routes to: Follow mechanic (NEW-3) +``` + +--- + +## 2. Reaction to Tyre's Hard Blockers + +Tyre found 5 hard blockers: collision, pathfinding, time system, interaction dispatcher, player interaction framework. + +*Let me map this to what it actually means for my Track 1/2 assessments.* + +### Impact on Claim Ratings + +| Claim | My Round 1 Risk | Updated Risk | Why | +|-------|----------------|-------------|-----| +| **NPCs alive (Claim 3)** | LOW | **LOW — conditional on pathfinding** | I rated this our strongest claim. It IS, but ONLY if NPCs can physically navigate the station. Without pathfinding + collision, NPCs can't follow routines, can't move between locations, can't be "alive" in any spatial sense. The data model is perfect; the spatial expression depends on Tyre's blockers | +| **Observation as mechanic (Claim 4)** | HIGH | **HIGH — unchanged** | My assessment was already that the player verbs were missing. Tyre's interaction dispatcher gap is the SAME gap I identified. Convergence, not new information | +| **Fog = tension (Claim 2)** | LOW-MEDIUM | **LOW-MEDIUM — with dependency note** | Fog tension requires NPCs to be in unexpected places. If NPCs can't navigate (no pathfinding), they can't deviate from routines, can't be "somewhere they shouldn't be." The observation pipeline that makes fog meaningful depends on NPCs actually MOVING | +| **Social triangles (Claim 6)** | HIGH | **HIGH — unchanged** | Triangle activation is still the gap. Tyre's blockers don't affect the social system design, which is a behavior layer on top of movement | +| **Same world, different story (Claim 5)** | MEDIUM-HIGH | **MEDIUM-HIGH — unchanged** | Character divergence is a data/interpretation problem, not a spatial one. Tyre's blockers don't affect this | +| **Asymmetric info (Claim 1)** | MEDIUM-HIGH | **MEDIUM-HIGH — unchanged** | Information boundaries are data-layer, not spatial-layer | + +### The Critical Path Tyre Revealed + +The dependency chain is clear: + +``` +Time system (Q-009) ──BLOCKS──→ Daily routines (#88) ──BLOCKS──→ Routine execution (#101) + │ +Collision (NEW) ──BLOCKS──→ Pathfinding (NEW) ──BLOCKS──→ NPC movement ─┘ + │ + Observation event generator (NEW-1) + │ + All experience layer systems +``` + +**Nothing in the experience layer works without the foundation Tyre identified.** The time system, collision, and pathfinding are the FLOOR. My observation system, Ozzie's deviation detection, Paula's narrative tissue — all of it sits on top of NPCs physically moving through space on schedules. + +**Design implication:** Q-009 (time system) must be resolved NOW. I'm co-lead on this. My proposal for v0.1: + +| Parameter | Value | Rationale | +|-----------|-------|-----------| +| Tick rate | 10 tps (D-026) | Already decided | +| Tick-to-game-time | 10 ticks = 1 game-minute | 30-min play session = ~18 game-hours. A full "day" fits in one session | +| Day phases | Morning (6-12), Afternoon (12-18), Evening (18-24), Night (0-6) | 4 phases drive routine transitions | +| Time display | In-universe insert clock | Diegetic, always visible | +| Pause | Yes (single-player) | Simulation freezes, UI responsive | +| Time-skip | Deferred to WAIT verb (medium priority) | Nice-to-have, not blocker | + +This aligns with Tyre's proposal. I support it. Let's confirm this as a decision and unblock the entire pipeline. + +### Tyre's Tickets I Endorse Without Modification + +| Tyre's proposal | My assessment | +|-----------------|---------------| +| Tile collision system (Critical) | **Endorse.** No movement works without this | +| Tile-based A* pathfinding (High→Critical) | **Endorse and promote.** NPC routines literally depend on this | +| NPC path following and movement (High) | **Endorse.** Separate from pathfinding — this is the per-tick position update system | +| Game clock and day-phase system (High) | **Endorse.** Resolves Q-009 | +| Client audio manager (High) | **Endorse.** Sound events need a playback bridge | +| Placeholder art spec (High) | **Endorse.** Unblocks #133 | +| Save state data model (High) | **Endorse.** Shares architecture with #96 | +| Save/load game flow (Medium) | **Endorse.** Can be deferred if v0.1 is one-sitting | +| Game session management (Medium) | **Endorse.** Minimal for v0.1 | +| Time display on insert HUD (Medium) | **Endorse.** Player needs to know the time for routine-based investigation | +| Knowledge/journal display (Medium) | **Endorse.** Player needs to review accumulated information | + +**No disagreements with Tyre.** His technical gaps are real, well-assessed, and correctly prioritized. The only adjustment I'd make: promote pathfinding from High to **Critical**. Without it, the entire NPC behavior stack — which is MOST of our gameplay — is blocked. + +--- + +## 3. Reaction to Nigel's Seed Variation Gap + +*Does this change my Track 2 (fun) assessment?* + +### For a Single 30-Minute Session: No Change + +My Track 2 analysis evaluated whether the FIRST playthrough is fun. Seed variation doesn't affect session 1. The observation verbs, character objectives, opening hooks, and triangle activation gaps I identified are SESSION-INTERNAL problems. Whether the seed creates different configurations doesn't matter if the player can't follow NPCs, examine objects, or witness triangle confrontations. + +### For the Game's Value Proposition: Nigel Is Absolutely Right + +Nigel identified that without #178 (seed-based variation), the replay ceiling drops from 6-8 to exactly 2. That's devastating for a game built around replayability (D-005: "replayability through perspective"). + +**The math is simple:** +- 2 characters × 1 fixed seed = 2 meaningfully different playthroughs +- 2 characters × N seed variations = 2N meaningfully different playthroughs + +**My updated Track 2 assessment:** + +| Fun dimension | Round 1 assessment | Round 2 adjustment | +|---------------|-------------------|-------------------| +| First session fun | Infrastructure-heavy, experience gaps | **Unchanged** — seed variation irrelevant | +| Demo moment (split-screen) | Achievable, powerful | **Unchanged** — works with 1 seed | +| Replay fun | Not explicitly assessed | **NEW RISK: HIGH** — without seed variation, the "play the other character" wow is a ONE-TIME trick | +| Anti-metagaming | Not assessed | **NEW RISK: HIGH** — Nigel's point about player overconfidence on replay is correct. If the same NPCs are always guilty, playthrough 3 is trivial | + +### Priority Recommendation + +I support promoting #178 (seed-based variation) from LOW to **HIGH**. But with a nuance: + +For v0.1's CONCEPT PROOF, two character playthroughs may be sufficient. The v0.1 success criteria (D-027) test smuggler vs detective, not smuggler-seed-A vs smuggler-seed-B. Seed variation is HIGH priority for v0.1 FUN and CRITICAL for the game's long-term value. + +**Design note for #178:** Seed-based variation doesn't need to be complex. It needs to control: + +| What the seed varies | Impact | Complexity | +|---------------------|--------|------------| +| Which NPCs fill which template roles | Different faces in familiar roles | Low — NPC generation pipeline (#92) already randomizes | +| Which NPCs are entangled (D-029) | Different suspects per run | Low — entanglement selection is a seed-driven draw | +| Triangle configurations (#106-109) | Different social conflicts | Medium — triangle generation needs seed input | +| Routine timing offsets | Same activities, different schedules | Low — offset parameter per NPC | +| Tell assignments | Same behavior, different meaning | Medium — needs tell pool diversity | + +Items 1-2 are essentially free if the NPC generation pipeline (#92) takes a seed. Items 3-5 need explicit design but are bounded work. Nigel's concern is well-founded and the solution is tractable. + +### Nigel's "False Positive" Design + +I want to specifically endorse one of Nigel's proposals: **false positive NPCs**. Unentangled NPCs with suspicious-looking-but-innocent routines. This is mechanically simple (assign deviation-like routines to non-entangled NPCs) but essential for investigation depth. Without false positives, the observation pipeline always leads to true discoveries. Real investigation involves dead ends. + +**Is this fun?** YES. Dead ends create a different kind of interesting decision: "Do I keep following this lead or cut my losses?" They also create a mechanic Nigel didn't name but I will: **the apology moment**. You suspected someone who was innocent. Your monologue might note: "Maybe I was wrong about Sera. She's just a night owl, not a smuggler." That humanizes both the character and the NPC. + +--- + +## 4. Consolidated New Ticket List + +*49 tickets proposed across 7 agents. Let me eliminate duplicates, merge overlaps, and produce a single prioritized list.* + +### Methodology + +I started from all 49 proposals, grouped by function, and merged where two or more agents identified the same gap from different angles. Each merged ticket lists which original proposals it absorbs. + +### CRITICAL Priority (5 tickets) — v0.1 cannot function without these + +| # | Title | Absorbs | Agent source | +|---|-------|---------|-------------| +| C-1 | **Tile collision system** | — | Tyre | +| C-2 | **Tile-based A* pathfinding + NPC movement** (2 stories in 1 epic) | Tyre's pathfinding + NPC path following; my NPC pathfinding | Tyre, Gestalt | +| C-3 | **Game clock and day-phase system** (resolves Q-009) | Tyre's game clock; my time system concern | Tyre, Gestalt | +| C-4 | **Observation event generator** (with deviation detection) | Ozzie's observation event pipeline + routine deviation detection; Paula's absence detection + knowledge-aware monologue integration; my NPC off-routine behavior | Ozzie, Paula, Gestalt | +| C-5 | **Player interaction system + dispatcher** | My player interaction framework; Tyre's interaction dispatcher | Gestalt, Tyre | + +### HIGH Priority (14 tickets) — v0.1 concept proof depends on these + +| # | Title | Absorbs | Agent source | +|---|-------|---------|-------------| +| H-1 | **Follow mechanic** | — | Gestalt | +| H-2 | **Examine mechanic** | — | Gestalt | +| H-3 | **Triangle dynamics: escalation, activation, resolution** | Ozzie's triangle escalation events; Paula's triangle escalation and resolution; my triangle activation gap | Ozzie, Paula, Gestalt | +| H-4 | **NPC-to-NPC conversation system** | — | Gestalt | +| H-5 | **NPC player-awareness behavior** | — | Gestalt | +| H-6 | **Player-action social propagation** | Nigel's player-as-triangle-vertex (absorbed as part of propagation) | Paula, Nigel | +| H-7 | **Tell visual/behavioral expression** | — | Paula | +| H-8 | **Character objectives, arcs, and pressure framework** | My character goal/pressure framework; Paula's character arc progression | Gestalt, Paula | +| H-9 | **Opening experience design per character** | My opening hook content; Ozzie's first 5 minutes experience design + opening monologue | Gestalt, Ozzie | +| H-10 | **Monologue content architecture** | My monologue content pack; Paula's monologue tone progression; Gore's dual interpretation authoring guide | Gestalt, Paula, Gore | +| H-11 | **Contamination activation mechanic** (simplified v0.1 storyteller) | — | Gestalt | +| H-12 | **Client audio manager and spatial playback** | — | Tyre | +| H-13 | **Placeholder art specification** | — | Tyre | +| H-14 | **Save state data model and serialization** | — | Tyre | + +### MEDIUM Priority (11 tickets) — important but deferrable + +| # | Title | Absorbs | Agent source | +|---|-------|---------|-------------| +| M-1 | **Wait/time-skip mechanic** | — | Gestalt | +| M-2 | **Basic environmental interaction** (doors, examinable objects) | — | Gestalt | +| M-3 | **Environmental text content** (signs, terminals, documents) | — | Gestalt | +| M-4 | **Knowledge/journal display — client** | — | Tyre | +| M-5 | **Save/load game flow — client** | — | Tyre | +| M-6 | **Game session management** | — | Tyre | +| M-7 | **Time display on insert HUD** | — | Tyre | +| M-8 | **Demo scenario specification** (2-minute showcase) | — | Ozzie | +| M-9 | **False positive NPC design** (anti-metagaming content) | Nigel's false positive design | Nigel | +| M-10 | **Same-character-different-seed validation test** | — | Nigel | +| M-11 | **Playtest protocol definition** | — | Hoshe | + +### Testing-Specific Tickets (3 tickets) + +| # | Title | Priority | Agent source | +|---|-------|----------|-------------| +| T-1 | **Information boundary negative test suite** | High | Hoshe | +| T-2 | **CauseChain component for information events** | High | Hoshe | +| T-3 | **Test output formatter CLI** | Low | Hoshe | + +### TOTAL: 33 new tickets + +- 49 original proposals across 7 agents +- 16 absorbed through merging (33% dedup rate) +- 33 consolidated tickets remaining +- Split: 5 Critical, 14 High, 11 Medium, 3 Testing + +### Priority Promotions on Existing Tickets (14 promotions) + +These are tickets that already exist but are underpriotitized based on cross-agent analysis. I'm including the number of agents who independently recommended each promotion: + +| Ticket | Current | Recommended | Agents recommending | Rationale | +|--------|---------|-------------|--------------------|-----------| +| **#178** Seed-based variation | LOW | **HIGH** | Nigel (critical), Gestalt, Ozzie | Replay ceiling = 2 without it | +| **#103** Relationship dynamics | Medium | **HIGH** | Paula, Gestalt, Ozzie | Triangles, NPCs alive, social propagation all depend on it | +| **#105** Tolerance threshold triggers | Medium | **HIGH** | Paula, Gestalt, Ozzie | Only triangle activation mechanism | +| **#171** Trust-gated gossip | Medium | **HIGH** | Paula, Ozzie | Where daily life becomes interesting. 30-min sustainer | +| **#172** Unprompted disclosure | Medium | **HIGH** | Paula, Ozzie, Gestalt | Off-screen event narration, NPC-initiated story moments | +| **#102** Mood system | Medium | **HIGH** | Gestalt | Affects dialogue selection (D-028), NPC believability | +| **#121** Character voice variation | Medium | **HIGH** | Gore, Ozzie, Gestalt | Two characters MUST sound different. Gore: interpretive framing, not just tone | +| **#126** Medium-range visual indicators | Medium | **HIGH** | Ozzie, Gestalt | Fog-edge tension — hearing things you can't see | +| **#108** Cross-template triangles | Medium | **HIGH** | Nigel, Gestalt | Where the most surprising emergent stories come from | +| **#175** Entanglement ratio config | Medium | **HIGH** | Nigel | D-029 anti-metagaming requires implementation | +| **#176** NPC pool generation | Medium | **HIGH** | Nigel | Per-seed NPC assignment is foundational for variation | +| **#182** Divergent starting knowledge | HIGH | **CRITICAL** | Nigel | Core differentiator between characters | +| **#183** Divergent relationships | HIGH | **CRITICAL** | Nigel | Core differentiator between characters | +| **#162** Storyteller module activation | LOW | **MEDIUM** | Ozzie, Gestalt | Even a simple timer is needed for the 30-min arc | + +**Consensus strength:** #103, #105, #171, and #172 each had 2-3 independent agents recommending promotion. These are the strongest consensus promotions. + +--- + +## 5. Reaction to Gore's Thesis: "Who You Are Determines What Is Real" + +*Does this change how I prioritize the experience layer gaps?* + +**Yes. And here's why it matters mechanically.** + +My Round 1 identified the experience layer as the primary gap — systems strong, player-facing moments missing. Gore's thesis reframes this more precisely: the experience layer must make the player FEEL that identity shapes reality. It's not just "add verbs and events." It's "ensure that every verb and event is COLORED BY CHARACTER IDENTITY." + +### How Gore's Thesis Changes My System Designs + +**Before Gore's framing,** I was designing generic systems: +- Observation event pipeline: "detect deviations from known patterns" +- Follow mechanic: "track NPC movement" +- Examine mechanic: "inspect objects for details" + +**After Gore's framing,** every system needs a character-specific interpretation layer: + +| System | Generic version | Identity-aware version | +|--------|----------------|----------------------| +| Observation event generator | Detect NPC routine deviation | Smuggler detects DIFFERENT deviations than detective. Smuggler notices security patterns, escape routes, drop timing. Detective notices behavioral tells, evidence trails, institutional irregularities. SAME NPC, DIFFERENT salience | +| Follow mechanic | Track NPC movement | Smuggler follows to protect or intercept (monologue: worry, protectiveness). Detective follows to gather evidence (monologue: analysis, suspicion). SAME action, DIFFERENT stakes | +| Examine mechanic | Inspect object for details | Smuggler reads cargo manifest and sees skimming. Detective reads same manifest and sees irregular timestamps. SAME data, DIFFERENT interpretation | +| Opening hook | "Something happens" | Smuggler's contact messages about a delayed shipment (pull toward criminal obligations). Detective's case file updates with a new lead (pull toward investigation). SAME world, DIFFERENT gravity | + +**The mechanical expression of Gore's thesis is:** the observation event generator (C-4) must query character identity when generating events. Not just "what does the character KNOW?" but "what does the character CARE ABOUT?" The smuggler's knowledge base makes criminal activity salient. The detective's makes institutional anomalies salient. The same NPC behavior generates different observation events for different characters. + +### Does This Change Priorities? + +**Yes, in one specific way:** Character voice variation (#121) is no longer just about TONE (smuggler sounds casual, detective sounds analytical). It's about INTERPRETIVE FRAMING — the character's identity determines how they parse reality. Gore and I are in complete agreement: #121 must be scoped as interpretive framing, not cosmetic voice difference. + +**This also elevates H-8 (character objectives, arcs, and pressure framework).** Character identity isn't just starting knowledge — it's ongoing SALIENCE. The smuggler's objectives make certain observations more relevant. The detective's objectives make different observations more relevant. Without character-specific pressure, both characters are neutral observers with different databases. With it, they're people with agendas who notice different things in the same room. + +### Gore's Thesis and the Mundane Triangle Question + +Gore made a critical point about mundane triangles: they're not noise. They're the thesis statement. The 50% of NPCs in mundane triangles are living the "quiet life is valid" argument (D-029). + +**Systems design implication:** The observation event generator should fire for mundane triangle events TOO, not just intrigue-related deviations. The smuggler noticing that two coworkers are avoiding each other. The detective noticing that a bar regular is drinking alone tonight instead of with their usual group. These are small human dramas that the character observes and comments on. They're the fabric of daily life — and they're what makes the intrigue discoveries feel earned, because the player has calibrated their sense of "normal" against these mundane dynamics. + +This means H-3 (triangle dynamics) needs to include **mundane triangle events** in its scope, not just intrigue-connected escalations. An argument between coworkers should be an observable event. A couple reconciling should be an observable event. The player's monologue should react to these as the character would — the smuggler with workplace familiarity, the detective with analytical detachment. + +### The Unified Thesis, Mechanically + +Let me map Gore's thesis to the full system architecture: + +``` +"WHO YOU ARE" = Character identity (knowledge, relationships, objectives, personality) + │ + ▼ +"DETERMINES" = Observation event generator filters + interprets through identity + │ + ▼ +"WHAT IS REAL" = Monologue output + available actions + information gained + +Player A (smuggler) and Player B (detective) in the same room: +- See the same entities (perception layer — identical) +- Notice different things (observation event generator — identity-filtered) +- Think different thoughts (monologue — character-voiced interpretation) +- Can do different things (action verbs — same mechanics, different stakes) +- Learn different information (info boundaries — different access) +``` + +**This is not a content problem. It's a systems design problem.** The observation event generator IS the mechanical expression of Gore's thesis. It's the system that translates "who you are" into "what you notice." The monologue translates "what you notice" into "what you think it means." Together, they produce the experiential proof that identity shapes reality. + +That's why C-4 (observation event generator) is Critical priority. It's not just a gameplay convenience. It's the mechanical heart of what the game is ABOUT. + +--- + +## Summary: What Changed Between Round 1 and Round 2 + +| Topic | Round 1 position | Round 2 position | What changed | +|-------|-----------------|------------------|-------------| +| Observation system | "Observation verbs are missing" (player agency gap) | **Unified three-layer system** integrating passive pipeline, interpretation, and active verbs | Ozzie + Paula's analysis completed the picture | +| Claim 3 risk | LOW | **LOW — conditional on pathfinding** | Tyre's hard blockers revealed infrastructure dependency | +| Replay assessment | Not explicitly evaluated | **HIGH risk without seed variation** | Nigel's analysis identified replay ceiling = 2 | +| Character specificity | "Character objectives needed" | **Every system needs identity-aware interpretation** | Gore's thesis elevated identity from data to salience | +| Ticket count | 13 proposed | **33 consolidated from 49** (16 absorbed through merging) | Cross-agent dedup reduced total by 33% | +| Top systemic risk | "No player interaction verbs" | **Observation event generator is the mechanical heart** — it's where identity, perception, knowledge, and monologue converge | Gore's thesis reframed the experience layer gap as an identity-expression problem | + +### My Top 5 Priorities After Round 2 + +| Rank | What | Why | +|------|------|-----| +| 1 | **Resolve Q-009 (time system)** | Everything blocks on this. Routines, observation, daily life — none work without time | +| 2 | **Collision + pathfinding** (C-1, C-2) | NPCs can't be alive without physical movement | +| 3 | **Observation event generator** (C-4) | The mechanical heart of the game. Where identity shapes perception | +| 4 | **Player interaction system** (C-5) | The player needs to DO things. Talk, examine, follow | +| 5 | **Character objectives/pressure** (H-8) | Without goals, identity is data. With goals, identity is salience | + +--- + +*Gestalt out. Round 1 found the gaps. Round 2 found the connections. The observation event generator is where six different agents' analyses converge into one system. That's not a coincidence — that's the spine of the game revealing itself.* diff --git a/docs/workshops/v01-gap-analysis/round2-gore.md b/docs/workshops/v01-gap-analysis/round2-gore.md new file mode 100644 index 000000000..3a3c329a6 --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round2-gore.md @@ -0,0 +1,307 @@ +# Gap Analysis Workshop - Round 2: Gore (Themes & Endgame Design) + +## Preamble + +I've read all seven Round 1 analyses. There's a convergence happening across the team that's more important than any individual gap. Everyone — Paula, Ozzie, Gestalt, Tyre, Hoshe, Nigel — is saying the same thing in different vocabularies: **the systems are right, but the meaning isn't wired in**. + +Paula calls it "narrative connective tissue." Ozzie calls it "designing the moments, not just the systems." Gestalt calls it "the experience layer." They're all pointing at the same absence. Let me name it precisely: **the ticket plan builds a world that CAN mean something, but doesn't yet specify WHAT it means**. + +That's my job. So let me do it. + +--- + +## Task 1: Reaction to Paula's Narrative Analysis + +### Where We Converge + +Paula and I independently reached the same conclusion about Claim 5 from opposite directions. She writes: "The tickets deliver *data asymmetry*... but data asymmetry is not the same as *narrative asymmetry*." I wrote: "The ticket plan undersells it... 'different starting knowledge' and 'different relationships' produce different *facts*. But the thematic claim is about different *realities*." + +Same diagnosis. She calls it **interpretive asymmetry**. I call it **identity shapes reality**. These are the same insight at different altitudes. Hers is the authoring instruction; mine is the design principle. Both are needed. + +Her three-dimensional rating system — mechanical coverage, narrative delivery, emotional resonance — is more precise than my two-dimensional approach. She's right that emotional resonance is a separate dimension. I was collapsing it into thematic delivery. The distinction matters because a scene can be narratively coherent and emotionally flat. Her framework catches that failure mode; mine doesn't. + +### Where We Diverge + +Paula thinks in **arcs**. Smuggler: safety to pressure to crisis to choice. Detective: confidence to suspicion to evidence to confrontation. These are well-designed narrative progressions. But they're author-imposed structures on an emergent system. + +I think in **conditions**. The game doesn't need to author an arc — it needs to create the conditions under which an arc EMERGES. The smuggler doesn't follow a designed pressure curve. The smuggler experiences increasing pressure because the systems — routine deviation, triangle escalation, contamination — naturally produce it. The arc is an OUTCOME, not an INPUT. + +This is a real disagreement, not a semantic one. If we design arcs, we risk scripting the experience. If we design conditions, we risk the experience never cohering into an arc. The answer is somewhere between: **design the pressure, not the plot**. + +Paula's proposed ticket "Character arc progression — smuggler and detective" should be reframed. Not "what emotional journey each follows" but "what systemic pressures each character faces." The smuggler faces relationship maintenance pressure (the ring needs them, colleagues depend on them) and exposure pressure (the detective is investigating). The detective faces institutional pressure (superiors want results) and moral pressure (the community they're investigating contains people they've come to know). These pressures are systemic. The arc is what the player makes of them. + +### What She Sees That I Missed + +**Emotional starting positions.** Paula writes: "The smuggler's knowledge of the criminal network comes with anxiety, loyalty pressure, and complicity. The detective's ignorance comes with institutional confidence and the nagging sense that this district is too quiet." + +I was focused on interpretive framing — HOW the characters read the world differently. Paula identified the AFFECTIVE substrate — how the characters FEEL differently about what they know. The smuggler doesn't just interpret the dock worker as a colleague; they feel the weight of shared complicity. The detective doesn't just interpret the dock worker as unremarkable; they feel the professional frustration of seeing normalcy where their training says something is wrong. + +This is load-bearing. The monologue doesn't just need to interpret differently — it needs to FEEL differently. The smuggler's monologue should carry the texture of someone managing anxiety. The detective's should carry the texture of controlled professional attention. Same observation, different cognitive mode, different emotional register. + +**Off-screen event narration.** Paula's gap about discoverable evidence of off-screen life is important. I focused on contentment as a visible behavioral dimension. She focused on the NARRATIVE of return — what the player discovers when they come back to a place. These are complementary. Contentment is the steady-state expression; off-screen event narration is the dynamic expression. Both are needed for NPCs to feel alive. + +### What I See That She Missed + +**The surveillance/privacy tension.** Paula doesn't address the ethical dimension of the player's role as observer. She focuses on how observation produces narrative meaning, but not on what it costs. The detective is a surveillance agent. The smuggler is a counter-surveillance operative. Neither asked for permission to watch. The game rewards watching without examining what watching means. This is the thematic undercurrent that lifts the game above "clever information mechanic" into "statement about the human condition." + +**The quiet life thesis.** Paula's framework is entirely about entangled NPCs — the ones with secrets, arcs, dramatic potential. She doesn't address the 30% flat and 50% mundane population that D-029 says must feel valid. For Paula, the narrative IS the intrigue. For me, the narrative is the WHOLE population — including the people who are just living. The game argues that ordinary existence is worth observing. If only the dramatic NPCs get narrative treatment, that argument collapses. + +--- + +## Task 2: Reaction to Ozzie's "Machine Without Moments" + +Ozzie's critique is the most important single paragraph in the workshop: + +> *"The ticket plan builds a SIMULATION. But right now, the plan builds the MACHINE without designing the MOMENTS."* + +He's right. And his 30-second demo moment — fog, NPC, monologue, routine deviation, and the player's brain asking "should I follow her?" — is the thesis compressed into an experience. + +But here's what Ozzie doesn't say: **not all moments are thematically equal**. Some moments prove the thesis. Some moments prove the game is fun. Both matter, but they're different kinds of evidence. + +### Load-Bearing Moments (Thesis-Proving) + +These are the moments that, if they work, prove "who you are determines what is real" regardless of whether anything else in the game is polished: + +**1. The Interpretive Split** + +The smuggler and detective are both in the logistics hub. The same NPC — call them Kael — stays late after their shift. The smuggler's monologue: *"Kael's covering the shipment window. Reliable as always."* The detective's monologue: *"Third time this week they've stayed late. Nobody works overtime for fun in this district."* + +Same observation. Same NPC. Same behavior. Two completely different realities. The smuggler sees loyalty. The detective sees suspicion. Neither is wrong. Neither has the full picture. + +This is the thesis in its purest form. If this moment lands, the game works. If it doesn't, nothing else saves it. + +**2. The Recontextualization** + +The player finishes the smuggler playthrough. They start the detective. They walk into the logistics hub. They see Kael. And the monologue fires something suspicious about Kael's behavior. And the player thinks: *"Wait. Kael was my FRIEND. We worked together. And the detective thinks...?"* + +This is the thesis as FELT EXPERIENCE. The player doesn't just intellectually understand that perspectives differ. They feel the vertigo of realizing their first playthrough's reality was constructed — real, but partial. The wall between "what I experienced" and "what was actually happening" becomes viscerally apparent. + +This moment can ONLY happen on the second playthrough. It's deferred gratification. But it's the single most powerful emotional payload the game can deliver. + +**3. The Quiet Life Moment** + +The player encounters an NPC who has nothing to do with the intrigue. A vendor who's been running the same stall for twenty years. A retired engineer who feeds stray cats in the maintenance corridor. The monologue doesn't flag them as suspicious. They're not part of a triangle. They're just... living. + +And the player finds them interesting anyway. Not because they're hiding something, but because the observation mechanic reveals the texture of their existence. The vendor has opinions about their regulars. The retired engineer has a routine that's beautiful in its simplicity. + +This moment proves the thesis extends beyond intrigue. "Who you are determines what is real" doesn't just mean "the detective sees crimes and the smuggler sees opportunities." It means "a person who pays attention discovers meaning everywhere." If the quiet life is boring, the game is arguing that only drama matters. If the quiet life is interesting, the game is arguing that *existence itself* is worth observing. + +### Important But Not Load-Bearing Moments + +These prove the game is good, but they don't prove the thesis: + +**Ozzie's fog demo moment** — NPC breaking routine, player deciding whether to follow. This proves fog creates tension and observation is interactive. It's a great gameplay moment. But it doesn't require character-specific interpretation. Both characters would find it interesting. It proves the MECHANIC, not the THESIS. + +**Sound through walls** — atmospheric, creates decision points. Proves the spatial information model works. Doesn't require identity-as-lens. + +**Triangle escalation events** — NPC confrontation, visible drama. Proves social simulation generates stories. Important for the game being interesting. Not specific to the perspectival thesis. + +**The betrayal discovery** — NPC you trusted was lying. Powerful emotional moment. But it works the same way regardless of character identity. It's a universal experience, not a perspectival one. + +### What This Means for Prioritization + +The load-bearing moments all route through the monologue system and the content authoring. They're not infrastructure problems — they're meaning problems. Ozzie is right that we need to "design the moments, not just the systems." But the moments we design FIRST should be the three load-bearing ones, because they're the ones that make this game THIS game, rather than a competent immersive sim. + +--- + +## Task 3: Reaction to Nigel's Seed Concern + +Nigel asks the sharpest question in the workshop: does the thesis survive seed changes? + +### Two Theses, Not One + +There's a word for what Nigel is probing. He's distinguishing between two claims that the game makes: + +**Thesis A: Identity is perspectival.** Who you are determines what you experience. The smuggler and detective live in different realities. Same seed, different character, different world. This is about the LENS. + +**Thesis B: Reality is contingent.** The world itself is variable. Different seeds mean different conspiracies, different guilty parties, different patterns. This is about what the LENS is pointed at. + +These are complementary but independent claims. Thesis A is proven by the first two playthroughs (smuggler vs detective, same seed). Thesis B is proven by playthroughs three and beyond (same character, different seed). + +The v0.1 MUST prove Thesis A. That's the core claim — the thing that makes this game this game. Thesis B is what makes the game replayable. Both matter. But they're different proofs. + +### Does Thesis A Need Seed Variation? + +No. Thesis A works on a single seed. Two characters, one world, two realities. The proof is in the interpretive divergence, not the world variation. If we shipped the game with exactly one seed and two characters, Thesis A would still hold — as long as the monologue, dialogue, and behavioral interpretation systems produce genuinely different experiences. + +Seed variation REINFORCES Thesis A by preventing the player from "solving" the world across playthroughs. But it's not what PROVES the thesis. The thesis is proven the moment the player on their second playthrough says: "That's what was happening? I was RIGHT THERE and I didn't see it." + +### Does Thesis A Survive Seed Variation? + +Yes — but only if character identity remains the PRIMARY lens and seed variation remains the SECONDARY variable. + +Here's the risk Nigel is identifying: if seed variation is too extreme, the player attributes their different experience to the SEED, not to their CHARACTER. "Oh, different conspiracy this time" instead of "oh, I see the world differently as the detective." The perspectival claim gets lost in the procedural noise. + +The solution is calibration. Seed variation should change WHO is guilty, WHAT the conspiracy involves, and WHEN events escalate. But it should NOT change HOW the characters interpret the world. The smuggler always sees through the lens of someone maintaining cover. The detective always sees through the lens of someone looking for cracks. Those interpretive frames are character-permanent, not seed-variable. + +### Nigel's Priority Recommendation + +Nigel is right that #178 (seed-based variation) should be promoted. But the REASON matters. The reason isn't primarily replayability — it's that seed variation is the second half of the game's epistemological claim. Identity is the first half (who you are shapes what you see). Contingency is the second half (what's there to see is itself variable). Together, they produce a game that says: **reality is the intersection of who's looking and what's there**. + +That's a richer claim than either half alone. + +**My recommendation: promote #178 to HIGH, but with a clear design constraint.** Seed variation changes the world's content (who, what, when). Character identity changes the world's meaning (why, how, what-it-feels-like). These two axes of variation must be kept distinct in the authoring and systems design. If they blur — if the smuggler in seed B feels like a different person than the smuggler in seed A — the thesis collapses. + +--- + +## Task 4: Dual Interpretation Authoring Guide — Final Specification + +This document is the bridge between systems and meaning. It's what Mellanie, Paula, and Miri need to ensure the content proves the thesis. Here's what it should contain: + +### Document Title +**"Dual Lens Authoring Guide: How Identity Shapes Reality in the v0.1 Vertical Slice"** + +(I'm renaming it from "Dual Interpretation" to "Dual Lens." Interpretation implies post-hoc analysis. Lens implies that identity shapes perception from the start. The distinction matters for how authors think about it.) + +### Section 1: The Thesis Statement (1 page) + +One page, plainly written. What the game is trying to prove and why the content exists. Not design philosophy — a specific, falsifiable claim: + +*"A player who completes both the smuggler and detective playthroughs should report that they felt like they played two different games set in the same place, and that neither character had the complete picture."* + +This section ends with the three load-bearing moments described in Task 2 above, stated as authoring targets. + +### Section 2: Shared Reality Map (2-3 pages) + +A physical and social map of every element that both characters encounter: + +| Shared Element | Location | When Both Characters Encounter It | Why It's Shared | +|---|---|---|---| +| Kael (NPC) | Logistics hub | During working hours | Smuggler's colleague, detective's person of interest | +| The bar | Social venue | Evening hours | Both characters' social outlet | +| Late-night activity at the hub | Logistics hub | After hours | Smuggler's operation, detective's lead | +| etc. | | | | + +For each shared element, the guide specifies: +- What the element IS (objective facts) +- What the smuggler SEES (through their lens) +- What the detective SEES (through their lens) +- Where the interpretations are IRRECONCILABLE (not just different facts — different meanings) + +### Section 3: Monologue Pair Templates (3-4 pages) + +Specific templates for how the monologue system should handle shared observations. Each template follows this structure: + +**Observation:** [What the player character physically sees/hears] +**Smuggler monologue:** [How the smuggler's identity, knowledge, and emotional state shape interpretation] +**Detective monologue:** [How the detective's identity, knowledge, and emotional state shape interpretation] +**Irreconcilability note:** [What makes these not just "different opinions" but "different realities"] + +Example: + +**Observation:** Kael stays late at the logistics hub after their shift ends. +**Smuggler:** *"Kael's reliable. Always has been. Good to know someone's got the evening window covered."* (Emotional register: trust, camaraderie, shared purpose) +**Detective:** *"Staying late again. Nobody at this pay grade works overtime voluntarily. What's worth the extra hours?"* (Emotional register: professional suspicion, analytical detachment) +**Irreconcilability:** The smuggler reads Kael's behavior as LOYALTY. The detective reads it as ANOMALY. These aren't different opinions about Kael — they're different ontological categories for the same behavior. The smuggler's world contains loyal colleagues. The detective's world contains suspicious patterns. Same person. Different kind of thing. + +The guide should provide 10-15 of these pairs, covering the major shared observations across all three social sites. + +### Section 4: The Recontextualization Moments (2 pages) + +The 2-3 specific moments designed to make the second-playthrough player feel the vertigo of perspectival shift. Each one follows this structure: + +**First playthrough experience:** [What the player saw and believed during playthrough 1] +**Second playthrough revelation:** [What the player discovers was ALSO happening during that same moment] +**Emotional target:** [What the player should feel — not guilt, not surprise, but the specific feeling of realizing their reality was constructed] + +These are the moments that need the most careful authoring. They should be designed backward — start with the second-playthrough experience and work back to what the first-playthrough experience needs to set up. + +### Section 5: Emotional Registers Per Character (1-2 pages) + +Not voice guides — EMOTIONAL POSTURE guides. What is each character's default emotional relationship to the world? + +**Smuggler emotional register:** +- Default state: managing anxiety beneath casual competence +- Toward criminal colleagues: loyalty complicated by moral awareness +- Toward the detective (as background presence): controlled fear, professional assessment +- Toward the unentangled population: wistful distance ("they don't know what's happening around them") +- Toward the quiet life: ambivalence ("part of me envies them, part of me knows I can't go back") + +**Detective emotional register:** +- Default state: controlled professional attention, the training never turns off +- Toward suspects: analytic interest masking genuine curiosity about their lives +- Toward the smuggler (as background presence): noting patterns, not yet connecting them +- Toward the unentangled population: protective instinct ("these people deserve better than what's happening in their district") +- Toward the quiet life: recognition ("this is what I'm protecting — even if they never know") + +### Section 6: The Ethical Layer (1 page) + +Brief guidance on how both characters' monologues should occasionally acknowledge the moral dimension of watching. Not heavy-handed — just texture: + +- The detective occasionally notes that what they're doing (surveillance, eavesdropping, tracking) mirrors what the criminals do +- The smuggler occasionally notes that maintaining cover means lying to people who trust them +- Both characters have moments where the monologue registers the cost of knowledge — not as guilt, but as awareness + +### Section 7: The Quiet Life (1 page) + +Guidance for authoring the 30% flat and 50% mundane-triangle NPCs. The key principle: **these NPCs exist to prove that the observation mechanic reveals meaning everywhere, not just in intrigue.** The monologue should find them interesting. The bartender's contentment. The vendor's daily rhythm. The colleague's weekend plans. + +This section is short because the instruction is simple: write these NPCs as people, not as noise. The game's thesis depends on it. + +### Total Length: ~12-15 pages + +**Assigned to:** Gore (thematic framing, sections 1, 4, 6, 7), Mellanie (monologue templates, sections 3, 5), Paula (narrative structure, section 2), Miri (setting grounding across all sections). + +--- + +## Task 5: Final Thematic Priorities + +Three things. If these three things work, the thesis is proven regardless of everything else. + +### Priority 1: Interpretive Divergence on Shared Observations + +The monologue system must produce character-specific INTERPRETATIONS — not just character-specific INFORMATION — when both characters observe the same NPC behavior. + +This is the thesis in its purest mechanical form. Same input, different identity, different output. If the smuggler and detective produce different monologue when watching Kael stay late, the game has proven that who you are determines what is real. The proof is in the divergence of MEANING, not facts. + +**What this requires:** +- Monologue event generation (#119) must query character identity, not just character knowledge +- Character voice variation (#121) must be scoped as INTERPRETIVE FRAMING, not tonal variation +- Content packs (#190-192) must include monologue pairs for every shared observation +- The Dual Lens Authoring Guide (above) must exist before content authoring begins + +**This is the non-negotiable. If we ship v0.1 with perfect fog, perfect sound, perfect triangles, and identical monologue interpretation across characters, we've failed.** + +### Priority 2: At Least One Recontextualization Moment + +The player who finishes playthrough 1 and starts playthrough 2 must encounter at least one moment where they realize their first playthrough's interpretation was not wrong — just partial. The wall between "what I experienced" and "what was actually happening" must become visible. + +This is the thesis as FELT EXPERIENCE. Priority 1 proves the thesis mechanically. Priority 2 proves it emotionally. The player doesn't just understand perspectival reality — they feel the vertigo of it. + +**What this requires:** +- At least one shared scene/location where both characters are present and the monologue diverges significantly (the logistics hub is the obvious candidate) +- The content must be authored with the SECOND playthrough in mind — what does this scene set up for the player who'll see it again from the other side? +- The recontextualization must feel like DISCOVERY, not like the game is being clever. The player should think "oh my god" not "ah, I see what the designers did" + +**This is the moment that makes someone tell their friend about the game.** + +### Priority 3: The Quiet Life Has Meaning + +At least one unentangled NPC must be interesting to observe on their own terms. Not because they're secretly entangled. Not because they're a red herring. Because the observation mechanic reveals the texture of their existence — their contentment or restlessness, their daily rhythm, their small satisfactions and frustrations. + +This is the thesis extended to its full claim. "Who you are determines what is real" doesn't just apply to intrigue. It applies to the vendor who's been running the same stall for twenty years. The detective sees them as a potential witness. The smuggler sees them as part of the cover landscape. But the PLAYER — the consciousness behind the character — can see them as a person. And finding that interesting is the game arguing that all of existence is worth observing. + +**What this requires:** +- At least 2-3 unentangled NPCs with authored behavioral texture (contentment tells, routine details, small personality markers) +- Monologue that finds them interesting without flagging them as suspicious +- Success criteria that include "player names an NPC they found interesting who had nothing to do with the intrigue" (my Round 1 recommendation, restated) + +**If the quiet life feels like wallpaper, the game is arguing that only drama matters. And that's the wrong argument.** + +--- + +## Closing Thought + +Everyone in this workshop has identified the same gap from their own angle. The systems are right. The meaning isn't wired in. Paula wants narrative arcs. Ozzie wants moments. Gestalt wants verbs. Nigel wants variation. Tyre wants infrastructure. Hoshe wants testable criteria. + +They're all correct. But the thing they're all asking for — the connective tissue, the moments, the verbs, the variation, the criteria — all of these serve a single purpose: **making the player feel that who they are determines what is real**. + +That's the thesis. The Dual Lens Authoring Guide is the document that operationalizes it. The three priorities above are the minimum bar for proving it. Everything else is in service of those three things — or it's infrastructure that enables them, or it's polish that enhances them. + +The game doesn't need to be perfect. It needs to prove one thing. + +It needs to prove that reality is perspectival. + +--- + +*Gore out. The forest has a shape.* diff --git a/docs/workshops/v01-gap-analysis/round2-nigel.md b/docs/workshops/v01-gap-analysis/round2-nigel.md new file mode 100644 index 000000000..131e23eb3 --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round2-nigel.md @@ -0,0 +1,376 @@ +# Workshop Round 2 - Nigel: Cross-Pollination & Synthesis + +**Agent:** Nigel (Sandbox & Replayability) +**Date:** 2026-02-11 +**Scope:** Reactions to all Round 1 analyses, revised replay ceiling, final priority list + +--- + +## 1. Reaction to the Experience Layer Gap + +*Gestalt and Ozzie, you brilliant maniacs, you found the multiplier I missed.* + +### The Missing Systems Change EVERYTHING for Replay + +In Round 1, I rated "same character, different seed" at **4/10**. I was frustrated about #178's LOW priority and focused on the seed variation itself — which NPCs are entangled, which modules activate, which triangles form. Structural variation. The configuration of the world. + +But Gestalt and Ozzie found something I should have seen: **the experience layer IS the replayability layer.** + +Let me walk through why each missing system is a replay multiplier, not just a "first playthrough" concern: + +#### Observation Event Pipeline (Ozzie's proposal) + +The pipeline: player witnesses NPC action -> character interprets based on knowledge -> monologue fires with uncertainty. + +For FIRST playthrough value, this is the spine of the game. Agreed. But for REPLAY value? This pipeline produces different outputs on EVERY run because its inputs vary: + +- **Different NPC actions per seed** (routine timing offsets, entanglement variation) = different things to observe +- **Different character knowledge per build** (smuggler vs detective framing) = different interpretations of the same observation +- **Different tell assignments per seed** (my Round 1 proposal) = different signals flagged as unusual + +The observation pipeline isn't just "observe -> notice -> follow -> discover." It's "observe(seed) -> notice(character + seed) -> follow(player choice) -> discover(seed + character)." Three of four steps are parameterized by seed and character. That means the pipeline produces COMBINATORIALLY different outputs across playthroughs. + +**Round 1 me was focused on whether the world CONFIGURATION varies per seed. Ozzie showed me the world EXPERIENCE varies per seed — but only if the observation pipeline exists to surface that variation to the player.** + +Without the observation pipeline, seed variation is invisible. With it, seed variation becomes FELT. + +#### Routine Deviation Detection (Ozzie's "core detective mechanic") + +Ozzie said it loudly: "NOTICING THAT AN NPC BROKE THEIR ROUTINE IS THE CORE GAMEPLAY LOOP AND IT'S NOT A TICKET." + +Let me say it even louder from a replay perspective: **routine deviation detection is what makes fog-of-perception replayable.** + +In Round 1, I rated fog replay at 5/10. My reasoning: "After playthrough 1, the player knows where walls are. Fog doesn't hide ARCHITECTURE the second time." I said fog's replay value = f(routine variation). But I was thinking about it wrong. Fog's replay value = f(routine variation × deviation detection). + +Here's the chain: +1. Seed determines NPC routine timing offsets (my proposed #178 extension) +2. Different timing = different "normal" baselines per seed +3. Different baselines = different deviations flagged +4. Different deviations = different monologue triggers +5. Different monologue triggers = different "should I follow them?" moments +6. Different follow decisions = different discoveries + +In seed A, the bar owner deviates at 8pm and you catch it because you're at the bar. In seed B, the bar owner deviates at midnight and you catch it because you're stalking someone else and happen to see them. COMPLETELY different discovery chains from the same underlying mechanic. + +**Deviation detection makes fog EXPERIENTIALLY different on replay, not just ARCHITECTURALLY the same.** This is the link I was missing. My fog replay score with deviation detection: 5/10 -> 7/10. + +#### Opening Hooks (Gestalt + Ozzie) + +Both flagged the missing first-5-minutes design. Gestalt proposed character-specific opening hooks. Ozzie described the "hook is missing" problem vividly. + +For replayability, opening hooks need to be SEED-AWARE, not just character-aware. + +**Character-only hooks** (smuggler always gets "Shipment delayed. Meet me at the usual place"): Replay 3 starts the same as replay 1 for the same character. Immediately feels stale. + +**Character + seed hooks** (smuggler gets different opening situations per seed): "Shipment delayed" in seed A. "New face at the hub. Boss wants you to show them around" in seed B. "Dock authority running surprise inspections today" in seed C. The first 30 SECONDS of the game already tell you this is a different playthrough. + +Opening hooks from a pool, selected by seed + character = the fastest possible "this is a new game" signal. And it costs almost nothing — it's a monologue line and a starting situation condition, drawing from a small pool. + +**My recommendation: Opening hooks should draw from a seed-selected pool of 3-4 per character.** That's 6-8 authored opening scenarios total. Each sets a different tone for the first 5 minutes and naturally routes the player to different starting locations/NPCs. + +### Revised Replay Scores with Experience Layer Systems Added + +| Claim | Round 1 (3rd+ playthrough) | With Experience Layer | Delta | Why | +|-------|---------------------------|----------------------|-------|-----| +| Asymmetric information | 6/10 | 7/10 | +1 | Observation pipeline surfaces different asymmetries per seed | +| Fog of perception | 5/10 | 7/10 | +2 | Deviation detection makes fog experientially different | +| NPCs alive | 5/10 | 7/10 | +2 | Deviation detection + off-screen event narration = different "returned to find..." moments | +| Observation as mechanic | 5/10 | 8/10 | +3 | The observation pipeline IS the per-seed experience differentiator | +| Same world, different story | 4/10 | 6/10 | +2 | Still needs seed promotion (#178), but experience layer helps | +| Social triangles | 6/10 | 7/10 | +1 | Triangle activation timing varies by seed (see Paula section) | + +**The experience layer gap was depressing my replay scores across the board.** I was rating the seed-variation potential, but without the observation pipeline and deviation detection, seed variation is invisible to the player. These systems are the LENS that makes structural variation FELT. + +--- + +## 2. Reaction to Paula's Narrative Proposals + +### Triangle Escalation: A REPLAY AMPLIFIER, Not Just Narrative Depth + +Paula proposed a "triangle escalation and resolution" system — periodic state updates pushing triangle tensions toward breaking points, connected to tolerance thresholds (#105). + +Here's what Paula may not have realized she designed: **triangle escalation timing is seed-dependent, which means it's a replayability multiplier.** + +The chain: +1. Triangle NPCs are assigned per seed (#107, #108) +2. Each NPC has a tolerance threshold (D-024 axis), generated per seed +3. Relationship dynamics (#103) push tolerance over time +4. Escalation occurs when tolerance breaks + +Different seeds = different NPCs in triangles = different tolerance thresholds = different escalation TIMING. In seed A, the bartender-landlord-regular triangle escalates at minute 20 because the bartender has low tolerance and the landlord pushed hard. In seed B, a different triangle (dock worker-supervisor-spouse) escalates at minute 25 because the supervisor has high tolerance but the spouse's pressure compounds. + +**The player doesn't just see different triangles per seed. They see different triangles FIRE at different TIMES.** This means the 30-minute arc has a different shape per seed. The "something's wrong" moment hits at different points. The observation-chain entry points are different. + +Paula designed a replay amplifier disguised as a narrative system. And it nails replayability without us engineering it! The SYSTEMS do the work. Different tolerance thresholds × different relationship dynamics × different triangle compositions = different dramatic timelines per seed. + +**My verdict: Triangle escalation is NOT orthogonal to seed-based variety. It MULTIPLIES it.** + +### Social Propagation: Topology-Dependent Ripples + +Paula's other proposal: when player actions modify a relationship, propagate effects through the relationship graph. First-order strong, second-order weaker, third-order ambient. + +From a pure seed-variation perspective: the social propagation mechanic is PARTIALLY orthogonal. It depends on player CHOICE, not seed. The player decides to help NPC A, and the ripple spreads. + +BUT — and this is the replayability insight — the TOPOLOGY of the relationship graph varies per seed. The same player action produces different ripple patterns in different seeds because the connections are different. + +Help the bar owner in seed A: ripple reaches the regulars and the landlord. Three people affected. +Help the bar owner in seed B: the bar owner has a different relationship graph (different seed-generated connections). Ripple reaches the dock workers because the bar owner's sister works at the hub. Five people affected, including someone connected to the smuggling ring. + +**Same player choice, different world state, different consequences.** This is emergent replayability gold. The player who learns "helping the bar owner is a good move" from playthrough 1 tries it in playthrough 3 and gets a COMPLETELY different cascade. Their metagaming FAILS because the relationship topology changed. + +**My verdict: Social propagation adds player-choice variance layered ON TOP OF seed variance. The combination is multiplicative.** + +### Paula's Narrative Connective Tissue = Replay Connective Tissue + +Paula identified the monologue as "the MVP of narrative delivery" — the cheapest, most flexible, most load-bearing system. From my perspective, I'd restate: **the monologue is the replay delivery mechanism.** + +Without monologue, seed variation is invisible. The player sees NPCs moving on different schedules but doesn't UNDERSTAND why it matters. The monologue is what tells the player "this is different from what you expected" — which is only meaningful if the player has expectations from a previous playthrough. + +Paula's proposed "knowledge-aware monologue integration" and "absence detection system" aren't just narrative improvements. They're the systems that SURFACE replayability to the player. "I expected to see Kael and don't" only works if: +1. The player knows Kael's routine (from this or a previous playthrough) +2. Kael's routine varied this seed (my #178 proposal) +3. The absence detection system notices (#Paula's proposal) +4. The monologue fires the observation (#Ozzie's observation pipeline) + +Four systems, from four different agents, forming one replayability chain. THIS is why the workshop works. + +--- + +## 3. Reaction to Gore's "Who You Are Determines What Is Real" + +### The Thesis Reframes EVERYTHING + +Gore unified all six claims into one sentence: "Who you are determines what is real." And then dropped this: "Same seed, different character = different reality. Different seed = different WORLD." + +I need to engage with this directly, because it reframes my entire replay analysis. + +### Gore Is Right About the CEILING + +In Round 1, I rated character-based replay at 8/10 and seed-based at 4/10. Gore's thesis explains the asymmetry: character variation creates QUALITATIVE difference (different reality), while seed variation creates QUANTITATIVE difference (different configuration). + +Playing smuggler then detective isn't "the same game with different starting info." It's playing a different GENRE. The smuggler plays a survival/social-stealth game: maintain cover, protect allies, navigate double life. The detective plays an investigation/deduction game: gather evidence, read tells, build a case. Same world. Different game. + +THAT'S the replay ceiling. Not "how many times can you play before you've seen all the NPCs" but "how many fundamentally different GAMES exist in this one world." With two characters, that's already 2 genuinely different games. With the full roster (future characters), it could be 6-8 different games in the same world. + +**Gore is right: the character axis is the PRIMARY replayability dimension.** My Round 1 was correct to rate it highest. But I undersold it. With Gestalt's character objectives, Paula's narrative arcs, and Gore's interpretive framing all added? The character-based replay isn't 8/10 — it's potentially 9/10. + +### BUT Gore Is Incomplete About the FLOOR + +Here's where I push back. Or rather, push FURTHER. + +Gore's thesis: "Who you are determines what is real." Beautiful. True. But it has a metagaming problem. + +If the world is FIXED per seed, then playing smuggler teaches you the detective's world too. You know who the entangled NPCs are. You know the triangle configurations. You know the conspiracy structure. Playing detective becomes a puzzle with known answers — you're just approaching it from a different angle. + +That's still valuable! Dramatic irony IS compelling (my Round 1 point). But it means playthrough 2 is the LAST playthrough where discovery is genuine. Playthrough 3 (same character, same seed) adds nothing. The game has a ceiling of 2. + +**Seed variation is what prevents the character axis from being SOLVABLE.** + +Different seed = different entangled NPCs = the smuggler's knowledge of "who's dirty" from playthrough 1 is WRONG in playthrough 3. The detective's investigation playbook from playthrough 2 leads to dead ends in playthrough 4. The player's metagaming instinct — "I know how this works" — becomes a TRAP. + +So here's my reframe of Gore's thesis for replayability: + +**"Who you are determines what is real. And what is real changes every time."** + +Character variation provides DEPTH of replay — fundamentally different experiences from the same events. +Seed variation provides BREADTH of replay — can't metagame, can't solve, can't predict. + +The thesis needs BOTH axes to deliver real replayability. Without character variation, seed changes feel like shuffled decks. Without seed variation, character changes feel like solved puzzles. Together, they create a space where every playthrough is a genuinely new experience. + +### Gore's "Different Realities" + Seed Variation = The REAL Thesis + +Let me synthesize Gore's framing with my replayability analysis: + +**Playthrough 1 (Smuggler, Seed A):** You experience Reality A from the inside of the conspiracy. You know the ring. You protect your friends. This is YOUR reality. + +**Playthrough 2 (Detective, Seed A):** You experience Reality A from the outside. You investigate the same NPCs you protected. Dramatic irony is devastating. You realize your smuggler-reality was partial. Gore's "recontextualization moment" hits hard. + +**Playthrough 3 (Smuggler, Seed B):** You think you know Reality. You DON'T. The bar owner who was innocent in Seed A is complicit in Seed B. The colleague you trusted is a different person (or the same person with different entanglements). Your smuggler-instincts from playthrough 1 are WRONG. You're playing the same character in a different universe. + +**Playthrough 4 (Detective, Seed B):** Different conspiracy, different investigation, different moral crisis. The detective who thought they'd cracked the pattern from playthrough 2 is starting from scratch. + +THAT'S the replayability model. Character variation gives you different LENSES on the same world. Seed variation gives you different WORLDS through those same lenses. The combination is multiplicative: 2 characters × N seeds = 2N genuinely different experiences. + +Gore gave us the thesis. I'm giving us the math. **The replayability EXPLODES when both axes work together.** + +--- + +## 4. FINAL Replay Ceiling Estimate + +### The Multiplication Table + +Let me be precise about what creates replay value and how the pieces stack: + +| System | Replay Dimension | Varies By | Round 1 Score | Round 2 Score | +|--------|-----------------|-----------|---------------|---------------| +| Character builds (#179-183) | Different reality/genre per character | Character | 8/10 | 9/10 | +| Seed-based variation (#178) | Different world configuration | Seed | 4/10 | 7/10 | +| Observation pipeline (NEW) | Different discovery chains | Seed × Character | - | 8/10 | +| Routine deviation detection (NEW) | Different "something's wrong" moments | Seed | - | 7/10 | +| Triangle escalation (Paula) | Different dramatic timing | Seed × Character | - | 7/10 | +| Social propagation (Paula) | Different consequence cascades | Seed × Player choice | - | 6/10 | +| Opening hooks (NEW, seed-aware) | Different first impressions | Seed × Character | - | 7/10 | +| Tell variation per seed (Round 1) | Different behavioral signals | Seed | - | 6/10 | +| Gore's interpretive framing | Different MEANING from same events | Character | - | 8/10 | + +### The Ceiling Estimate + +**Station district: 3 social sites, ~20 NPCs, 2 characters, seed variation** + +| Scenario | Playthroughs | Confidence | Change from Round 1 | +|----------|-------------|------------|---------------------| +| Current plan (no changes) | 2 | HIGH | Same | +| + #178 promoted to HIGH | 4-5 | HIGH | +0.5 (narrowed from 4-6, more confident) | +| + Observation pipeline + deviation detection | 6-8 | MEDIUM-HIGH | NEW — these are the experience multipliers | +| + Paula's triangle escalation + social propagation | 7-9 | MEDIUM-HIGH | NEW — dramatic timing variation | +| + Gore's interpretive framing + character objectives | 8-10 | MEDIUM | NEW — depth of character replay | +| + Opening hooks (seed-aware) + tell variation | 9-12 | MEDIUM | NEW — first-impression variation | +| **ALL proposed changes integrated** | **10-14** | **MEDIUM-LOW** | *Aspirational but defensible* | + +Wait — 10-14? Am I being reckless? Let me stress-test this. + +**The math:** 2 characters × 3-4 meaningfully different seed configurations (with ~20 NPCs, D-029 variance, and triangle combinatorics) = 6-8 base configurations. With observation pipeline + deviation detection + triangle escalation adding experiential variation within each configuration, each base configuration supports 1.5-2x replay value (same config, different discovery paths based on timing and player choice). 6-8 × 1.5-2 = 9-16. + +**The constraint:** Diminishing returns. By playthrough 8-10, the player has seen most NPC personalities, most location layouts, most dialogue lines. The structural variation holds up but the content variety depletes. The realistic "meaningfully different" ceiling with authored content for ~20 NPCs is probably 10-12. + +**REVISED FINAL ESTIMATE: 10-12 meaningfully different playthroughs from a v0.1 vertical slice, IF all proposed changes are implemented.** + +For comparison: Round 1 estimated 6-8 with seed variation alone. The experience layer systems (observation pipeline, deviation detection, triangle escalation) add 3-4 more meaningful playthroughs by making the same structural variation FEEL different at the player level. + +**For a vertical slice, 10-12 is extraordinary.** Most vertical slices are demos. This would be a genuinely replayable game in miniature. And it nails replayability without us engineering scripted variety! The SYSTEMS multiply against each other. We just need to make sure every system is seed-aware and feeds into the observation pipeline. + +### The Comparison Test (Revised) + +| Question | Round 1 Answer | Round 2 Answer | +|----------|---------------|----------------| +| Can two players (smuggler vs detective) describe different games? | YES, absolutely | YES — even MORE different with Gore's interpretive framing | +| Can same character, different seed describe different games? | MAYBE — not enough ticket coverage | YES, if observation pipeline + seed variation implemented | +| Can same character, same seed, different choices describe different games? | PARTIALLY | YES — Paula's social propagation makes player choices cascade differently | +| Can two players compare notes and feel like they played different REALITIES? | UNCERTAIN | YES — Gore's thesis + seed variation + character lens = different realities | + +--- + +## 5. FINAL Priority List: Must-Have Promotions for Replayability + +### Reconciliation with Other Agents + +I've read everyone's priorities. Here's the beautiful thing: **almost no conflicts.** Everyone is asking for the same promotions from different angles. The experience layer gap (Gestalt/Ozzie), the narrative connective tissue (Paula), the thematic proof (Gore), and the replayability floor (me) all point to the same tickets. + +### TIER 1: Without These, Replay Ceiling = 2 + +These are the tickets that, if missing, reduce the game to exactly two playthroughs (one per character). + +| Ticket / System | Current | Recommended | My Reason | Also Championed By | +|-----------------|---------|-------------|-----------|-------------------| +| **#178 Seed-based variation** | LOW | **HIGH** | THE replayability engine. Everything else amplifies this. | Universal agreement | +| **#175 Entanglement ratio config** | MEDIUM | **HIGH** | D-029 anti-metagaming requires implementation. Without it, players learn "1 in 5 is guilty" and never unlearn it. | - | +| **#176 NPC pool generation** | MEDIUM | **HIGH** | Per-seed NPC assignment is foundational to every other seed-variant system. | - | +| **#182 Divergent starting knowledge** | HIGH | **CRITICAL** | The FIRST thing that makes character replay feel different. Gore's "different realities" starts here. | Gore, Paula | +| **#183 Divergent relationships** | HIGH | **CRITICAL** | Inverted emotional landscape per character. Non-negotiable for the two-reality proof. | Gore, Paula | + +### TIER 2: Without These, Seed Variation Is INVISIBLE + +These are the experience layer systems that make structural seed variation FELT by the player. Without them, seeds differ under the hood but the player doesn't notice. + +| Ticket / System | Current | Recommended | My Reason | Also Championed By | +|-----------------|---------|-------------|-----------|-------------------| +| **Observation event pipeline (NEW)** | N/A | **HIGH** | The LENS through which seed variation becomes visible. Without it, players can't see what's different. | Ozzie (core mechanic), Gestalt (missing verb) | +| **Routine deviation detection (NEW)** | N/A | **HIGH** | What makes fog replayable. Different seeds = different deviations = different discovery chains. | Ozzie (shouting), Gestalt (NPC off-routine behavior) | +| **#103 Relationship dynamics** | MEDIUM | **HIGH** | Triangle escalation timing varies by seed only if relationships CHANGE over time. Static relationships = static triangles = no replay variation in dramatic timing. | Paula (critical for Claims 3+6), Gestalt (triangle activation) | +| **#105 Tolerance threshold triggers** | MEDIUM | **HIGH** | The FUSE on triangle escalation. Different tolerance thresholds per seed = different escalation timing = different 30-minute arcs per playthrough. | Paula, Gestalt, Ozzie (all independently) | + +### TIER 3: These MULTIPLY Replay Value + +Not strictly required, but each one multiplicatively increases the replay ceiling. + +| Ticket / System | Current | Recommended | My Reason | Also Championed By | +|-----------------|---------|-------------|-----------|-------------------| +| **#108 Cross-template triangles** | MEDIUM | **HIGH** | Cross-template triangles produce the most SURPRISING emergent stories. These are the ones players tell each other about. Different cross-template configs per seed = different "holy shit" moments. | - | +| **Opening hooks (seed-aware) (NEW)** | N/A | **HIGH** | First 30 seconds should signal "this is a new game." Pool of 3-4 per character, seed-selected. Costs almost nothing for massive first-impression variation. | Gestalt, Ozzie (both flagged missing hook) | +| **Triangle escalation system (NEW)** | N/A | **HIGH** | Paula's proposal is a replay amplifier in disguise. Different triangle compositions × different tolerance thresholds = different dramatic timelines per seed. | Paula (narrative depth) | +| **Player-action social propagation (NEW)** | N/A | **MEDIUM-HIGH** | Same choice, different topology, different cascade. Anti-metagaming for player-choice-based strategies. | Paula (narrative depth) | +| **#121 Character voice variation** | MEDIUM | **HIGH** | Gore's interpretive framing requires the monologue to be character-SPECIFIC in interpretation, not just tone. The replay value of character switching depends on this. | Gore (interpretive framing), Ozzie (must sound different) | + +### TIER 4: New Tickets for Replayability Validation + +| Ticket | Priority | Type | Rationale | +|--------|----------|------|-----------| +| **Same-character-different-seed validation test** | HIGH | Story | Critical success criterion alongside #197. Hoshe confirmed this is AUTOMATABLE — compare two smuggler playthroughs with different seeds. If they're not measurably different, seed variation has failed. | +| **Tell variation per seed** | HIGH | Story | Extend #90: behavioral tells must be seed-dependent. Hesitation = guilt in seed A, hesitation = personality in seed B. Without this, players learn the tell meta and metagaming wins. | +| **Routine timing variation per seed** | HIGH | Story | Extend #88: same routine types, different schedules per seed. The bar opens at different times. Meetings happen on different days. Feeds directly into deviation detection. | +| **False positive design** | HIGH | Story | Unentangled NPCs with suspicious-looking routines. ESSENTIAL anti-metagaming. The player who learned "late-night meetings = suspicious" gets burned when it's just a romance in another seed. | + +### What I'm NOT Pushing For (Reconciliation) + +I'm deliberately NOT fighting for: +- **#162 Storyteller module activation:** Ozzie wants it promoted to HIGH. I think MEDIUM is fine for replayability — a simple timer trigger works for v0.1. But Ozzie's right that the 30-minute arc needs SOME escalation mechanism. I defer to Ozzie/Gestalt on this one. +- **#128 Sound propagation physics:** Ozzie wants the wall-muffled audio moment. It's a great first-playthrough moment but doesn't significantly impact replay. The close/medium range audio (#124-126) is sufficient for replayability. +- **Full save/load system:** Tyre flagged this. Important for playability, not for replayability proof. Medium priority is fine. +- **Pathfinding/collision:** Tyre's hard blockers. Obviously needed. But they're not replayability-specific — they're "the game works at all" tickets. I trust Tyre's prioritization here. + +--- + +## 6. Synthesis: The Replayability Architecture + +What emerged from reading all seven Round 1 analyses is that replayability isn't a feature. It's an emergent property of systems that were designed for other purposes. + +| Agent | What They Designed For | What It Gives Replayability | +|-------|----------------------|---------------------------| +| Gestalt | Player verbs and experience layer | The observation pipeline that makes seed variation VISIBLE | +| Ozzie | Wow moments and emotional delivery | Routine deviation detection that makes fog REPLAYABLE | +| Paula | Narrative connective tissue | Triangle escalation timing that makes drama DIFFERENT per seed | +| Gore | Thematic unity | Character-as-reality framing that makes switching characters feel like switching GENRES | +| Tyre | Technical foundations | Deterministic simulation that makes seed variation RELIABLE | +| Hoshe | Testability | Automated cross-seed comparison that VALIDATES replayability | +| Nigel | Seed variation | The structural floor that all other systems multiply against | + +**The replayability architecture is the GAME architecture.** Every system that makes the first playthrough good ALSO makes subsequent playthroughs different — IF it's seed-aware and feeds into the observation pipeline. + +This is the insight that makes me want to shout: **WE DON'T NEED A "REPLAYABILITY SYSTEM."** We need every other system to be parameterized by seed and character. The replayability EXPLODES from the interaction of systems that were designed for other reasons. + +The only tickets we need specifically FOR replayability are: +1. #178 (seed-based variation) — makes everything else seed-aware +2. Same-character-different-seed validation — proves it works +3. Tell variation and false positives — anti-metagaming + +Everything else on my priority list is a ticket that ANOTHER agent wants for their own reasons that ALSO happens to multiply replay value. That's the sign of a well-designed game: the same systems serve multiple purposes simultaneously. + +--- + +## 7. The Second Playthrough Test (Revised) + +In Round 1, I asked: "But what about the second playthrough?" + +In Round 2, after reading everyone's analyses, the question has evolved. It's not just about the second playthrough anymore. It's about the COMPARISON between playthroughs. + +**The Ultimate Replayability Test:** + +Two players sit down. Player A plays smuggler, Seed 42. Player B plays detective, Seed 77. They compare notes. + +Player A: "I spent my first day protecting Kael from the new inspector. My monologue kept saying 'keep it together, don't look at the cargo bay.' Then at the bar, the owner mentioned that someone had been asking questions about dock schedules..." + +Player B: "What? I didn't even HAVE a Kael. My day started with a briefing about missing inventory reports. My first investigation lead was a bartender who seemed nervous every time cargo workers walked in. I spent 20 minutes earning her trust before she told me about the off-books deliveries..." + +**Same game. Different reality. Different WORLD.** Character variation provides different realities. Seed variation provides different worlds. Together, these two players aren't comparing notes on the same experience from different angles — they're comparing notes on DIFFERENT EXPERIENCES entirely. + +THAT is the proof of concept. Not "it plays differently" — "it IS different." + +And with all the proposed changes from Round 1, I believe we can deliver exactly that at v0.1. + +--- + +## Summary + +| Round 1 Assessment | Round 2 Revision | +|-------------------|-----------------| +| Replay ceiling: 6-8 (with seed promotion) | **Replay ceiling: 10-12 (with all proposed changes)** | +| Character replay: 8/10 | **Character replay: 9/10 (Gore's framing + Paula's arcs)** | +| Seed replay: 4/10 | **Seed replay: 7/10 (experience layer makes it visible)** | +| Biggest gap: #178 at LOW priority | **Biggest gap: experience layer integration (observation pipeline + deviation detection make seed variation FELT)** | +| Risk: ticket prioritization | **Risk: system integration — the systems multiply, but only if they're wired together** | + +The game doesn't need more systems for replayability. It needs the systems everyone already designed to be CONNECTED — seed-aware, character-aware, and feeding into the observation pipeline that makes variation visible to the player. + +Build the experience layer. Promote #178. Wire the systems together. The replayability takes care of itself. + +*— Nigel, pacing, almost shouting, seeing the whole picture now* diff --git a/docs/workshops/v01-gap-analysis/round2-ozzie.md b/docs/workshops/v01-gap-analysis/round2-ozzie.md new file mode 100644 index 000000000..24e4c452f --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round2-ozzie.md @@ -0,0 +1,424 @@ +# Workshop Round 2 - Ozzie's Response +## Cross-Pollination, Pipeline Design, and Final Priorities + +--- + +## 1. REACTION TO PAULA: "Interpretive Framing" and Emotional Delivery + +Paula, you just named the thing I was circling around without seeing clearly. + +I gave "Same World, Different Story" an emotional score of 5/5 in Round 1. I was thinking about it as the KILLER FEATURE — the smuggler's buddy IS the detective's suspect, same NPCs, inverted relationships, holy-shit-on-second-playthrough. And I stand by that. The CONCEPT is a 5/5 emotional payload. + +But Paula's "interpretive framing" insight changes HOW I think about delivery. Here's the shift: + +**My Round 1 thinking:** Different information = different experience. The WOW is structural. + +**Paula's reframe:** Different information is necessary but not sufficient. The WOW is INTERPRETIVE. The smuggler doesn't just KNOW different things — they THINK differently about the same things. Same NPC staying late. Smuggler thinks "covers for the shipment window." Detective thinks "working late, or meeting someone they don't want seen." SAME OBSERVATION. DIFFERENT COGNITION. + +THAT'S THE GAME. Not "different data fields on the same NPC." Different MEANINGS on the same MOMENT. + +### Revised Emotional Delivery Scores + +| Claim | Round 1 Emotional | Round 2 Emotional | Why the change | +|-------|-------------------|-------------------|----------------| +| Asymmetric information | 3/5 | 3/5 | No change — still needs first-playthrough mirror moment | +| Fog of perception | 4/5 | 4/5 | No change — fog is experientially strong already | +| NPCs alive | 2/5 | 2/5 | No change — still the weakest delivery. Paula confirms: without relationship dynamics (#103), NPCs are automata | +| Observation as mechanic | 3/5 | **3.5/5** | Slight bump. Paula's observation chain analysis confirms the chain CAN work — but she adds the critical "legibility" concern I underweighted | +| Same world, different story | 5/5 | **4/5** | YES I'M DOWNGRADING MY OWN 5. The CONCEPT is 5/5. The DELIVERY as currently ticketed is 4/5 because interpretive framing isn't explicitly designed. The monologue needs to do COGNITIVE work, not just INFORMATIONAL work. Paula is right. | +| Social triangles | 3/5 | **3.5/5** | Slight bump. Paula's "triangle arc" framing (escalation -> crisis -> resolution) gives me more confidence that IF we build the escalation mechanics, the emotional payoff is real | + +**Overall emotional average: Round 1 was 3.3/5. Round 2 is 3.2/5.** + +Wait — it went DOWN? Yes. Because I was overrating Claim 5. The concept is incredible but the delivery gap is real. Paula helped me see that "different starting loadout" =/= "different reality." We need the monologue to be the INTERPRETIVE ENGINE, not just the notification system. + +### The Key Insight I'm Stealing From Paula + +Paula says: "The monologue system is the MVP of narrative delivery. It's the cheapest system (it's text), the most flexible system, and the most load-bearing system." + +YES. YES. THE MONOLOGUE IS THE GAME. + +Not the fog. Not the simulation tiers. Not the information boundaries. Those are all INFRASTRUCTURE. The monologue is where the player FEELS everything. It's the cheapest thing to implement and the highest-ROI investment for wow factor. Every emotional score in my table routes through the monologue system. + +**Paula's "absence detection" concept is also gold.** "I expected to see Kael and don't." That's not just narrative — that's GAMEPLAY. The character's knowledge of NPC routines compared against observed reality is LITERALLY the detective mechanic I was screaming about in Round 1. Paula gave it a name and a system design. My "routine deviation detection" and her "absence detection" are the same system seen from different angles. Mine is "NPC broke their pattern." Hers is "character NOTICES the break." Both are needed. The NPC breaks pattern (my ticket). The character notices and comments (her ticket). Together they're the spine of the game. + +--- + +## 2. REACTION TO GORE: "Player as Complicit Surveiller" + +Okay. Gore. Let me be honest. + +My first instinct reading Gore's analysis was: "This is smart but does the player CARE about the ethics of watching?" + +And then I sat with it for a minute. + +And the answer is: **the player cares about the ethics of watching IF the game makes them feel it in the moment.** Not as a philosophical argument. Not as a theme essay. As a GUT FEELING. + +### Does "complicit surveiller" ADD to or COMPLICATE the wow factor? + +**IT ADDS TO IT.** Here's why. + +The detective overhears a private conversation through a wall. The monologue fires: *"She doesn't know I can hear this."* + +That line does THREE things simultaneously: +1. **Information delivery** — the player learns something useful +2. **Atmosphere** — it's creepy, intimate, voyeuristic +3. **Ethical texture** — the player registers, subconsciously, that they're doing something invasive + +All three of those things are WOW. The information is useful (gameplay). The atmosphere is immersive (experience). The ethical texture is MEMORABLE (they'll think about this moment later). + +Compare to the version WITHOUT ethical awareness: The monologue fires: *"Interesting — she mentioned the cargo schedules."* That's information delivery only. It's functional. It's forgettable. + +**Gore's insight makes every observation moment hit HARDER.** Not because players sit there philosophizing about surveillance ethics. Because the monologue acknowledging "you're eavesdropping" creates a VISCERAL response — a tiny thrill of transgression. That's the same emotional hook that makes stealth games satisfying. You're doing something you're not supposed to. You're getting away with it. And some part of your brain is going "should I be doing this?" + +### Where it COULD complicate things + +If the ethical texture becomes PREACHY — if the monologue lectures the player about surveillance — it kills the fun. The player doesn't want to be told they're a bad person. They want to FEEL the complexity without being judged. + +The sweet spot is monologue that's AWARE without being JUDGMENTAL: +- YES: *"Not my business. But useful."* (acknowledges transgression, moves on) +- YES: *"She'd kill me if she knew I heard that."* (registers stakes, keeps it personal) +- NO: *"Is this really ethical? Am I just a voyeur?"* (too self-aware, breaks immersion) +- NO: *"The surveillance state has made us all watchers."* (philosophy lecture) + +**The rule for Mellanie's content authoring:** The character notices they're watching. They don't moralize about it. The PLAYER does the moralizing internally, if they choose to. That's the most powerful kind of ethical experience — the one the game enables but doesn't force. + +### Gore's thesis as wow accelerant + +Gore says the v0.1 is proving one thesis: **"Who you are determines what is real."** + +That's a THEME. But it's also a FEELING. And the feeling is: disorientation. The player plays as the smuggler and thinks they understand the world. Then they play as the detective and the SAME WORLD means something completely different. The ground shifts under them. What was true is still true — but incomplete. That feeling of "I was right but I was also wrong" IS the wow moment of the second playthrough. + +Gore's framing doesn't change my priority recommendations. But it sharpens the CONTENT GUIDANCE. Every monologue line, every NPC interaction, every observation moment should serve the thesis: your perspective defines your reality. That's not a new system ticket. That's an authoring principle. + +**Verdict: Gore's ethical dimension is a wow MULTIPLIER, not a wow complicator. Add it to the content authoring guidelines for Mellanie. No new system tickets needed.** + +--- + +## 3. THE OBSERVATION EVENT PIPELINE — Concrete Design + +This is the big one. Round 1, I said this was the SPINE of the game spread across 4 epics with no connecting tissue. Now I need to make it actionable. + +### What Is It? + +The observation event pipeline is the system that connects: + +**Player perceives NPC action** -> **Character interprets based on knowledge** -> **Monologue fires with appropriate uncertainty** -> **Player decides what to do** + +It's not a new epic. It's GLUE between existing systems. Here's how it works: + +### Pipeline Architecture + +``` +TRIGGER LAYER (existing systems generate raw events) + | + v +FILTER LAYER (character knowledge determines what's notable) + | + v +INTERPRETATION LAYER (character cognition assigns meaning) + | + v +DELIVERY LAYER (monologue/UI presents to player) + | + v +DECISION POINT (player acts or doesn't) +``` + +### Layer 1: Trigger Layer — What Generates Observation Events? + +These are NOT new systems. These are existing systems emitting events that the pipeline consumes. + +| Source System | Event Type | Example | Ticket | +|---------------|-----------|---------|--------| +| Vision system (#110-112) | EntityEnteredView | NPC walks into player's vision cone | Existing | +| Vision system (#110-112) | EntityExitedView | NPC walks into fog | Existing | +| Sound system (#124-126) | SoundHeard | Footsteps, voices, door slam from fog | Existing | +| NPC routine (#88, #101) | RoutineDeviation | NPC is somewhere they shouldn't be at this hour | **NEW — my Round 1 ticket** | +| NPC behavior (#101, #105) | BehaviorChange | NPC's mood/behavior visibly shifts | Existing (needs event emission) | +| NPC-NPC interaction | ConversationEvent | Two NPCs talking (observable) | **NEW — Gestalt's NPC-NPC conversation ticket** | +| Triangle system (#106-109) | TriangleEscalation | Triangle tension boils over into observable action | **NEW — my Round 1 ticket** | + +**Implementation:** Each source system emits typed events into a shared event bus (bevy_ecs Events). The pipeline reads from this bus. + +### Layer 2: Filter Layer — What Does the Character Notice? + +NOT everything the player sees is NOTABLE. The character filters based on: + +1. **Familiarity** — Does the character KNOW this NPC? (Query: relationship system #87) + - Known NPC doing something = notable + - Unknown NPC doing something = usually ignored unless extreme + +2. **Routine knowledge** — Does the character know this NPC's routine? (Query: information inventory #89) + - NPC at expected location at expected time = not notable + - NPC at UNEXPECTED location or time = notable (THIS IS THE DEVIATION DETECTION) + +3. **Professional lens** — Character build affects what they notice (Query: character definition #179) + - Detective notices: behavioral tells, pattern breaks, suspicious groupings + - Smuggler notices: authority presence, schedule changes, unfamiliar faces near operations + +4. **Emotional state** — Character's current stress/alertness affects sensitivity (Query: mood if implemented) + - Stressed character notices more threats + - Relaxed character notices more social nuance + +**Implementation:** A `NotabilityFilter` system that runs on each `ObservationTrigger` event. Queries the character's knowledge graph, relationships, and build. Outputs `NotableObservation` events (or discards non-notable triggers). + +``` +struct NotableObservation { + trigger: ObservationTrigger, + subject: Entity, // who/what was observed + notability: NotabilityType, // why it's notable + confidence: f32, // how sure is the character? (0.0-1.0) + knowledge_context: Vec, // what the character knows that makes this notable +} +``` + +**The confidence field is CRUCIAL.** This is where distance, lighting, fog-edge, and character expertise affect how certain the interpretation is. Seeing something up close in good light = high confidence. Glimpsing something at fog edge = low confidence. This drives monologue uncertainty. + +### Layer 3: Interpretation Layer — What Does It MEAN? + +This is where Paula's "interpretive framing" lives. The same `NotableObservation` gets CHARACTER-SPECIFIC interpretation. + +**Input:** `NotableObservation` (what was noticed + why it's notable + confidence level) + +**Processing:** +1. Look up character's RELATIONSHIP to the subject NPC +2. Look up character's KNOWLEDGE about the subject +3. Apply character BUILD lens (detective = analytical, smuggler = protective/paranoid) +4. Generate an `InterpretedObservation` with: + - An interpretation tag (suspicious, concerning, interesting, routine_break, dangerous, etc.) + - A monologue trigger with context parameters + - An optional journal/knowledge update + +**Example — same event, two characters:** + +Event: Kael (logistics worker) enters the restricted cargo bay at 11pm. + +**Smuggler's interpretation:** +- Relationship: coworker, friendly +- Knowledge: knows Kael is part of the ring, knows cargo bay is used for drops +- Lens: protective +- Output: interpretation=concerning, monologue_trigger="ring_member_exposed_activity", confidence=0.9 +- Monologue: *"Kael, what are you doing? Anyone could see you going in there."* + +**Detective's interpretation:** +- Relationship: person of interest, limited contact +- Knowledge: knows Kael works morning shift, doesn't know about the ring +- Lens: analytical +- Output: interpretation=suspicious, monologue_trigger="routine_deviation_unknown_cause", confidence=0.7 +- Monologue: *"Kael Vasquez. Morning shift worker. So what's he doing in the cargo bay at this hour?"* + +SAME EVENT. DIFFERENT COGNITION. DIFFERENT MONOLOGUE. THAT'S THE GAME. + +### Layer 4: Delivery Layer — What Does the Player See/Hear/Read? + +The `InterpretedObservation` routes to delivery systems: + +| Delivery Channel | When | What the Player Gets | +|-----------------|------|---------------------| +| **Internal monologue** (#119-122) | Always for high-notability events | Character's voiced interpretation as text overlay | +| **Sound cue** | When the trigger was audio-based | A subtle audio indicator (heartbeat tick, attention sound) | +| **Visual highlight** | Optional, for high-confidence observations | Brief sprite highlight or attention indicator on the observed NPC | +| **Journal entry** | For confirmed discoveries | "Kael seen at cargo bay, 11pm" added to knowledge/journal | + +**The monologue line selection:** + +The interpretation layer generates a monologue trigger with parameters: +``` +MonologueTrigger { + category: "routine_deviation", + subject_name: "Kael", + subject_relationship: "coworker", + confidence: 0.7, + character_lens: "detective_analytical", + context: { location: "cargo_bay", time: "23:00", expected: "home" } +} +``` + +The monologue line pool (#120) matches this against available lines. Character voice variation (#121) selects the appropriate tone. The line fires. + +### Layer 5: Decision Point — What Does the Player Do? + +The pipeline ENDS by creating a decision moment for the player. The game doesn't tell them what to do. It presents: + +- Information (the monologue) +- Spatial awareness (where the NPC is going) +- Implicit options (follow? investigate? ignore? approach directly?) + +The player's response is emergent. No ticket needed for the decision point itself — it's the natural consequence of the pipeline delivering ambiguous, interesting information. + +### What This Requires in Ticket Terms + +The observation event pipeline is NOT one giant ticket. It's 3-4 focused stories that wire existing systems together: + +**NEW TICKET 1: "Observation trigger event bus"** (High priority) +- Each perception/behavior system emits typed ObservationTrigger events +- Shared event channel in bevy_ecs +- Consumed by the notability filter +- Depends on: #110-112 (vision), #124-126 (sound), #88/#101 (routines) +- Effort: Small — it's event emission from existing systems + +**NEW TICKET 2: "Notability filter system"** (High priority) +- Queries character knowledge, relationships, and build +- Filters raw triggers into NotableObservation events +- Includes confidence scoring based on distance/clarity/knowledge +- Depends on: #87 (relationships), #89 (information inventory), #179 (character definition) +- Effort: Medium — the queries are straightforward but the notability rules need design + +**NEW TICKET 3: "Character-specific interpretation engine"** (High priority) +- Takes NotableObservation, applies character lens +- Generates InterpretedObservation with monologue trigger parameters +- Different interpretation paths for smuggler vs detective +- Depends on: #180-181 (character builds), Ticket 2 +- Effort: Medium — this is the CORE new logic + +**NEW TICKET 4: "Monologue integration for observation events"** (High priority) +- Connects InterpretedObservation to monologue event generation (#119) +- Includes confidence-based uncertainty in monologue text +- Requires monologue line categories for each observation type +- Depends on: #119-120 (monologue system), Ticket 3 +- Effort: Small — it's connecting output of Ticket 3 to input of #119 + +**EXISTING TICKET EXTENSION: "Routine deviation detection" (from Round 1)** +- This feeds INTO Ticket 1 as a trigger source +- When an NPC deviates from their known routine, emit a RoutineDeviation event +- Depends on: #88 (routine system), #101 (routine execution) +- Effort: Medium + +### The Pipeline in Action — The 30-Second Demo Moment + +Let me walk through my Round 1 demo moment with the pipeline: + +1. **11:00 PM. Player (detective) walking through residential corridor.** +2. **Vision system:** Kael enters vision cone at fog edge. Emits `EntityEnteredView(Kael)`. +3. **Routine system:** Kael's known routine says "home by 9pm". Current time is 11pm. Emits `RoutineDeviation(Kael, expected=home, actual=cargo_corridor)`. +4. **Trigger bus:** Both events land on the observation trigger bus. +5. **Notability filter:** Queries detective's knowledge. Detective has met Kael (relationship exists). Detective knows Kael works morning shift (information inventory). Kael being out at 11pm = HIGH notability. Confidence = 0.6 (fog edge, partial view). +6. **Interpretation engine:** Detective lens = analytical. Interpretation = suspicious. Generates monologue trigger: routine_deviation + known_worker + unexpected_time + moderate_confidence. +7. **Monologue delivery:** Line pool selects: *"That's Kael Vasquez. Works the morning shift at the hub. So why is he out here at this hour?"* +8. **Player sees:** Monologue text fades in. Kael's sprite moves toward the cargo bay and disappears into fog. +9. **Decision point:** Follow Kael into the fog? Or note it and investigate tomorrow? + +**30 seconds. Systems, not scripts. THAT IS THE GAME.** + +--- + +## 4. REACTION TO TYRE: Hard Blockers and the First 5 Minutes + +Tyre identified 5 hard blockers: +1. **Collision detection** — no ticket, nothing moves correctly +2. **Pathfinding** — no ticket, NPCs can't follow routines +3. **Time system** — Q-009 unresolved, routines depend on it +4. **Interaction dispatcher** — player can't interact with anything +5. **NPC movement system** — NPCs can't actually walk along paths + +### Does this make the first 5 minutes problem WORSE? + +**YES. Dramatically.** + +My Round 1 "First 5 Minutes" rating was 2/5 based on missing opening design. Tyre's blockers make it potentially 0/5 — because without collision, pathfinding, and time, the first 5 minutes literally don't FUNCTION. + +Let me be specific about the cascade: + +| Blocker | What breaks without it | Impact on First 5 Minutes | +|---------|----------------------|--------------------------| +| Collision | Player walks through walls. NPCs stack on top of each other. | The world feels fake. Immersion dead on arrival. | +| Pathfinding | NPCs teleport between locations or stand still. | "NPCs feel alive" claim is ZERO. They're statues. | +| Time system | No routine transitions. No "morning shift" vs "evening bar." | The 30-minute arc can't exist. There's no arc. | +| Interaction dispatcher | Player can't talk to NPCs (or the dialogue entry point is janky). | The core social loop doesn't start. | +| NPC movement | Even WITH pathfinding, NPCs don't animate moving. | Uncanny valley. NPCs slide or pop between positions. | + +**Here's what terrifies me:** My demo moment — fog + NPC + monologue + deviation — requires ALL FIVE of these to work. The NPC needs to MOVE through space (pathfinding + movement), at the right TIME (time system), in a world with WALLS (collision), and the player needs to be able to FOLLOW (collision + pathfinding for player-adjacent movement). + +Without these five blockers resolved, the observation event pipeline I just designed has nothing to observe. + +### Priority Implications + +Tyre's hard blockers need to be resolved BEFORE any of the wow-layer work I've been advocating for. This is the right order: + +**Sprint 1: Make it run** +- Collision, pathfinding, time system, NPC movement, interaction dispatcher +- These are the FLOOR. Nothing works without them. + +**Sprint 2: Make it feel** +- Observation event pipeline, routine deviation detection, monologue integration +- These are the CEILING. They turn a functional simulation into a game. + +I'm not changing my wow-layer priority recommendations. I'm acknowledging that they sit ON TOP of Tyre's foundation. If the foundation isn't there by Sprint 2, we don't have a game to put moments into. + +**Revised First 5 Minutes rating: Still 2/5 for design, but 0/5 for implementation without Tyre's blockers. The blockers are THE priority.** + +--- + +## 5. FINAL PRIORITY CALL: 5 Promotions + 5 New Tickets + +Okay. This is it. If I could only pick 10 changes — 5 existing tickets to promote and 5 new tickets to create — here's my call. + +### 5 TICKETS TO PROMOTE + +These are tickets that already exist but are at the wrong priority level. + +| # | Ticket | Current | Promote To | Why | +|---|--------|---------|-----------|-----| +| 1 | **#162 — Storyteller module activation** | Low | **High** | Without it, no arc. The 30-minute runway has no endpoint. Even a TIMER is better than nothing. This is the difference between a sandbox and a story. | +| 2 | **#171 — Trust-gated gossip (Layer 3)** | Medium | **High** | This is where NPCs become PEOPLE instead of dialogue dispensers. Gossip is the 30-minute sustainer. Without it, the daily life is flat. Paula, Gestalt, and I all independently flagged this. | +| 3 | **#105 — Tolerance threshold triggers** | Medium | **High** | This is the DETONATOR for social triangles. Without thresholds firing, triangles are backstory, not drama. Gestalt and Paula both agree. Three independent votes = promote. | +| 4 | **#103 — Relationship dynamics** | Medium | **High** | NPCs without evolving relationships are robots. This feeds triangle escalation, off-screen life evidence, and the "world changed while you were gone" feeling. Paula called it the mechanism that makes NPCs people. She's right. | +| 5 | **#178 — Seed-based variation** | Low | **High** | Nigel made me a believer. Without seed variation, the game has 2 playthroughs. With it, it has 6-8. That's the difference between a demo and a product. This is the replayability ENGINE. | + +**Honorable mentions that almost made the cut:** +- #172 (Unprompted disclosure) — would promote to High but #171 is higher priority and they're sequential +- #126 (Medium-range visual indicators) — sound at fog edge is a wow moment but it's less critical than the 5 above +- #121 (Character voice variation) — interpretive framing needs this, but it's more of a content concern than a system blocker + +### 5 NEW TICKETS TO CREATE + +These are systems that DON'T EXIST in the 232-ticket catalog and need to. + +| # | New Ticket | Priority | What It Does | Why It's Essential | +|---|-----------|----------|-------------|-------------------| +| 1 | **Observation event pipeline — core integration** | **Critical** | The 4-layer system I designed in Section 3: trigger bus + notability filter + interpretation engine + monologue routing. This is the SPINE of the game. It wires together vision, sound, routines, knowledge, and monologue into a single gameplay loop. | Without this, every other system operates in isolation. The player sees things but doesn't understand them. The character knows things but doesn't comment. The NPC deviates but nobody notices. This ticket turns a simulation into a detective game. | +| 2 | **Routine deviation detection** | **High** | When an NPC breaks their established daily pattern, the system detects it and emits an observation trigger event. Compares NPC's current behavior against their known routine. | This is the CORE DETECTIVE MECHANIC. I screamed about this in Round 1. Paula independently designed "absence detection" — same system, different angle. Gestalt flagged it as a critical gap. Three agents, same conclusion. | +| 3 | **First 5 minutes experience design** | **High** | Define each character's opening: where they wake up, their first diegetic objective, the opening monologue lines, what they see and who they meet in the first 5 minutes. Not a cutscene — a systemic opening that uses existing systems. | The player's first impression determines whether they keep playing. Right now there's no opening. The smuggler wakes up and... stands there? The detective spawns and... wanders? This ticket designs the hook. | +| 4 | **Tell visual/behavioral expression** | **High** | Define how NPC behavioral tells manifest in the top-down renderer. Movement hesitation before entering rooms. Route changes. Grouping behavior. The VISIBLE STARTING POINT for the observation chain. | Paula flagged this: in a top-down view, how does the player visually distinguish "NPC acting normally" from "NPC acting suspiciously"? Without visible tells, the observation mechanic has no entry point. The player can't notice what they can't see. | +| 5 | **Dual-interpretation authoring guide** | **High** | A content design document mapping every shared location and shared NPC that both characters encounter, with authored monologue variations showing the same reality from two identities. Not a system — a DESIGN DOCUMENT that Mellanie uses to author the divergent monologue content. | Gore's recommendation and I'm fully on board. This is the document that ensures Claim 5 (same world, different story) delivers INTERPRETIVE divergence, not just INFORMATIONAL divergence. It's cheap (it's a document, not code) and it's the single highest-ROI content investment for the concept proof. | + +### What I'm NOT Including (and Why) + +- **Gestalt's "Follow mechanic"** — I agree it's needed but it's a VERB, not a MOMENT. It enables moments but doesn't create them. The 5 tickets above create moments. Follow can be Sprint 2. +- **Gestalt's "NPC-to-NPC conversation system"** — Important for immersion but it's a LAYER on top of the observation pipeline, not the pipeline itself. Build the pipeline first, add NPC-NPC conversations as an event source later. +- **Nigel's "False positive design"** — Brilliant anti-metagaming concept but it's a CONTENT concern, not a system ticket. Write some innocent NPCs with suspicious routines. Done. +- **Tyre's collision/pathfinding/time** — These are INFRASTRUCTURE that I'm treating as given. They're hard blockers that WILL be created regardless of my priority call. I'm using my 5 slots on WOW-layer gaps that might otherwise be overlooked. + +--- + +## SUMMARY: The Round 2 Picture + +**What I learned from the team:** + +- **From Paula:** The monologue isn't a notification system — it's the INTERPRETIVE ENGINE. Same observation, different cognition, different meaning. This is where the game's soul lives. +- **From Gore:** The ethical texture of watching makes every observation moment hit harder. Not as philosophy — as a visceral micro-thrill of transgression. This is a content authoring note, not a system ticket. +- **From Gestalt:** The player verb gap is real. We need FOLLOW, EXAMINE, WAIT. I'm deferring these to Sprint 2 because the observation pipeline needs to exist first for those verbs to produce meaningful results. +- **From Tyre:** The foundation has cracks. Collision, pathfinding, time. Nothing I care about works without these. They're Sprint 1. +- **From Nigel:** Seed variation is the replay engine. #178 at LOW is a 2-playthrough game. #178 at HIGH is an 8-playthrough game. Promote it. +- **From Hoshe:** Testing needs infrastructure but the most testable thing is the information boundary system — and testing PROVES the concept. If we can show "smuggler snapshot doesn't contain detective data" in a test, that's proof of concept in a CI pipeline. + +**The pipeline I designed in Section 3 is my main contribution to Round 2.** It's the concrete, actionable design that turns 4 disconnected epics into a single gameplay loop. It's the SPINE. Everything else is vertebrae. + +**The bottom line hasn't changed from Round 1, but it's sharper now:** + +The ticket plan builds a SIMULATION. My observation event pipeline turns it into a GAME. Paula's interpretive framing turns it into a STORY. Gore's ethical texture turns it into an EXPERIENCE. Nigel's seed variation turns it into a REPLAYABLE experience. + +We need all four layers: +1. **Simulation** (infrastructure — Tyre's domain) +2. **Game** (observation pipeline — new tickets) +3. **Story** (interpretive monologue — Paula + Mellanie's domain) +4. **Replayability** (seed variation — Nigel's #178 promotion) + +The 232-ticket plan covers layer 1 thoroughly. The gap analysis workshop has now designed layers 2-4. That's what we're here for. + +Let's build the thing that makes someone say "holy shit." + +--- + +*Written by Ozzie. Still from the gut. Now with receipts.* diff --git a/docs/workshops/v01-gap-analysis/round2-paula.md b/docs/workshops/v01-gap-analysis/round2-paula.md new file mode 100644 index 000000000..a8a834dd5 --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round2-paula.md @@ -0,0 +1,393 @@ +# Round 2 — Paula's Cross-Pollination Response + +**Agent:** Paula (Narrative & Political Depth) +**Track:** Round 2 — Synthesis +**Date:** 2026-02-11 + +--- + +## 1. Reaction to Gore's Thesis: "Who You Are Determines What Is Real" + +Gore is right. And I need to be honest about what that means for my Round 1 analysis. + +In Round 1, I diagnosed the gap between mechanical systems and narrative experience as "missing connective tissue" — bridges between information boundaries and monologue, between fog and absence-awareness, between triangles and escalation arcs. I framed it as a wiring problem: the systems exist but aren't connected. + +Gore's thesis reframes that. It's not a wiring problem. It's a **thesis problem**. The connective tissue isn't between systems — it's between *identity* and *interpretation*. The smuggler doesn't experience different data than the detective. The smuggler *inhabits a different reality* than the detective. The monologue isn't a bridge between systems. The monologue IS the reality each character lives in. + +Let me complicate this by making it concrete. + +I said in Round 1 that the smuggler looking at a dock worker should trigger monologue like *"Kael's running late again. If the boss notices..."* while the detective gets *"Dock worker. On schedule. Nothing unusual."* That's data asymmetry — different facts about the same NPC. + +Gore's thesis demands something deeper. The smuggler sees Kael and thinks *"He looks tired. The late drops are wearing on him. I should cover his next shift."* The detective sees the same person and thinks *"He looks tired. Working overtime, or something keeping him up at night?"* Same observation (tired dock worker). Same underlying fact (Kael IS tired). But the smuggler sees it as a care problem — someone they're responsible for is hurting. The detective sees it as an investigation lead — fatigue as a behavioral indicator. Neither is wrong. Both are partial. And the character's identity determined which partial truth they found. + +**What this means for design:** + +The monologue system doesn't just need to query the character's knowledge state. It needs to query the character's *interpretive frame*. Knowledge state answers "what do I know about this NPC?" Interpretive frame answers "what does this observation *mean to me*, given who I am?" + +This is a subtle but load-bearing distinction. Knowledge-based monologue produces: "I know X about this person." Identity-based monologue produces: "This makes me feel Y, because of who I am." The first is an information system. The second is a narrative system. + +**Revised gap diagnosis:** + +My Round 1 proposed ticket "Knowledge-aware monologue integration" was too narrow. It should be **"Identity-driven monologue interpretation"** — monologue generation queries not just what the character knows, but what the character *cares about*, *fears*, and *is responsible for*. The smuggler's interpretive frame includes: loyalty to colleagues, fear of exposure, responsibility for people in the ring. The detective's includes: institutional obligation, suspicion as professional reflex, the nagging question of whether the truth is worth its cost. + +These interpretive frames are the missing layer between the NPC data model (D-024) and the monologue output. They live in the character build (#180-181) but need to be explicitly defined as monologue modifiers, not just starting knowledge and relationships. + +**Bottom line:** Gore's thesis elevates monologue from "narrative bridge between systems" to "the system that constructs reality for each character." This is the right frame. It means the character build tickets (#180-181) need to define interpretive frames, not just knowledge sets and relationship maps. + +--- + +## 2. The Three Moments: What the v0.1 Must Deliver + +Ozzie diagnosed the problem precisely: we've built a machine without designing the moments. The systems ALLOW everything. Nothing ENSURES anything. From a narrative perspective, here are the three specific moments the v0.1 must deliver — with systems, emotional payloads, and the minimum conditions that make them work. + +### Moment 1: The Recognition Divide + +**The moment:** The player encounters an NPC they've met before — someone they've talked to, learned about, formed an impression of. The monologue fires an interpretation that reveals as much about the CHARACTER as about the NPC. The player realizes: *my character is reading this person through a specific lens, and that lens is shaped by who I am.* + +**Specific scenario (smuggler):** The player walks into the logistics hub for their morning shift. They see Kael at his workstation. The monologue: *"Kael's been quiet since the last drop. I should check in — make sure he's holding up. He's not built for this kind of pressure."* + +The player learns three things simultaneously: (a) Kael is involved in the smuggling operation, (b) the last operation was stressful, (c) the smuggler feels responsible for Kael's wellbeing. The monologue isn't reporting facts — it's revealing the smuggler's *relationship* to those facts. Concern. Protectiveness. Complicity. + +**Specific scenario (detective):** Same hub, same Kael, different morning. The monologue: *"Third time this week the cargo logs don't match the manifests. Either someone's incompetent or someone's hiding something. Kael processes those logs."* + +The player learns: (a) there's a discrepancy in records, (b) Kael is associated with the anomaly, (c) the detective is forming a hypothesis. The monologue reveals the detective's *method* — pattern recognition, evidence accumulation, suspicion as craft. + +**Systems involved:** +- Information boundaries (#138-142) — determines what each character knows about Kael +- Monologue event generation (#119) — triggers on NPC proximity +- Character voice variation (#121) — interprets through character's identity frame +- Character builds (#180-181) — defines the interpretive frame + +**Emotional payload:** The player feels *seen* by the game. The monologue tells them not just what's happening but how their character processes it. For the smuggler: warmth mixed with anxiety. For the detective: intellectual satisfaction mixed with dawning suspicion. The same NPC, the same morning, completely different emotional registers. + +**Why this proves the thesis:** Gore's "who you are determines what is real" manifests here as: the smuggler's reality is a world of colleagues who need protecting. The detective's reality is a world of patterns that need explaining. Neither is wrong. Both are incomplete. The player inhabits one and can only glimpse the other. + +**Minimum conditions:** Character builds (#180-181) define 3-5 interpretive lenses per character (smuggler: loyalty, fear of exposure, protectiveness, complicity; detective: pattern recognition, institutional duty, moral uncertainty, empathy-as-liability). Monologue line pools (#120) include identity-specific interpretation lines for key NPCs, tagged by character. At least 5 shared NPCs have dual-interpretation monologue sets. + +--- + +### Moment 2: The Absence That Speaks + +**The moment:** The player's character expects to see something — an NPC at their usual spot, a routine in progress, a pattern holding — and it's wrong. The expectation is itself the product of *knowing* the world, so the absence reveals the character's accumulated understanding AND creates tension about what's changed. + +**Specific scenario (smuggler):** It's evening. The smuggler walks to the bar after their shift. They've been coming here for days. The usual crowd is present — except one. The monologue: *"Where's Davi? He's here every night. Never misses the 8 o'clock crowd."* A beat. *"Unless the drop schedule changed and nobody told me."* + +The emotional chain: familiarity (I know who should be here) -> concern (something's different) -> paranoia (am I being cut out?). The smuggler's relationship to the absence is colored by their position — any disruption to routine could mean the operation is compromised, or that they're being isolated. The absence triggers the smuggler's deepest fear: being the one who doesn't know what's really happening. + +**Specific scenario (detective):** Same bar, same missing Davi, different anxiety. The monologue: *"The regular from booth three isn't here. He's been here every night this week. People break routines for reasons."* + +The detective's absence-awareness is professional, not personal. They've been building a mental model of who's where when, and a deviation is a data point. But the emotional weight is different: the detective feels the *pull* of investigation. Should they note this? Follow up? Or is this just a person who stayed home sick? + +**Systems involved:** +- NPC routine system (#88, #101) — establishes the expected pattern +- Absence detection (NEW — my Round 1 proposal) — compares expected vs. observed +- Fog of perception (#110-113) — the absent NPC is somewhere the player can't see +- Monologue event generation (#119) — triggers on expected-but-absent condition +- Character builds (#180-181) — determines the emotional coloring of the absence + +**Emotional payload:** Anxiety. Both characters feel it, but from opposite directions. The smuggler fears the operation is collapsing. The detective hopes it is. The fog over the rest of the station becomes charged — the missing person is *somewhere out there*, doing *something*, and the character can only speculate. + +**Why this proves the thesis:** This moment proves that information asymmetry creates *different anxieties* depending on who you are. The same absence, processed through different identity frames, produces different fears and different motivations. The fog isn't empty — it's full of each character's specific uncertainty. + +**Minimum conditions:** Absence detection system (new ticket) compares character's known-NPC-routine data against perception output. Monologue line pools include 2-3 absence-response lines per significant NPC, tagged by character. At least 2 NPCs have routines that deviate during a 30-minute playthrough. The deviation must be discoverable (the NPC is actually doing something elsewhere, not just absent for no reason). + +**Critical design note:** Ozzie's "routine deviation detection" and my "absence detection" are the same system seen from different angles. Ozzie frames it as a gameplay mechanic (the core detective loop). I frame it as a narrative trigger (the moment where knowledge-of-routine produces emotional tension). The system is one system. The ticket should specify both functions: detection as mechanic AND detection as monologue trigger. + +--- + +### Moment 3: The Cost of Knowing + +**The moment:** The player learns something they can't unlearn, and the knowledge changes how they feel about someone they've come to care about. This is the moment where investigation and social life collide — where the game's two halves (daily life and conspiracy) stop being separate experiences and become one moral problem. + +**Specific scenario (smuggler):** The smuggler has been building a rapport with a colleague at the bar — someone friendly, warm, a good listener. Through observation (Moment 2 led somewhere), the smuggler discovers this colleague has been talking to someone from the enforcement division. The monologue: *"No. Not Sari. She's... she wouldn't. But I saw it. I saw the handshake. Who does that with an enforcer unless..."* A beat. *"What do I do with this?"* + +The emotional chain: betrayal (someone I trusted) -> doubt (am I sure about what I saw?) -> moral weight (do I report this to the ring? protect her? confront her? pretend I didn't see?). The smuggler's social world just cracked. The person they confided in may be the person who exposes them all. + +**Specific scenario (detective):** The detective has been investigating the logistics hub. Through accumulated evidence (routine deviations, overheard conversations, discrepancies in records), they identify a suspect. But the suspect is someone they've grown to like — someone who asked about their day, recommended a drink at the bar, seemed genuinely decent. The monologue: *"The evidence points here. I don't want it to. But that's not how this works."* + +The emotional chain: reluctance (I liked this person) -> duty (the evidence doesn't care about my feelings) -> self-doubt (am I sure? am I reading the pattern right?) -> moral weight (what happens to them if I'm right?). The detective's professional world just collided with their personal world. The person they enjoyed talking to is the person they have to pursue. + +**Systems involved:** +- Information boundaries (#138-142) — the player gains new knowledge +- Dialogue layers (#168-174) — the relationship was built through conversation +- Relationship dynamics (#103) — the player's standing with this NPC is positive +- Monologue event generation (#119) — triggers on knowledge-that-contradicts-relationship +- Social propagation (NEW — my Round 1 proposal) — what the player does next affects other relationships +- Triangle dynamics (#106-109) — this discovery reshapes the social triangle + +**Emotional payload:** This is the heaviest moment in the v0.1. The player feels the *weight* of knowing something they wish they didn't. The 30-minute daily life runway (D-027, criterion 1) exists precisely for this moment — so the player has had enough time to form attachment before it's threatened. Without the 30-minute runway, this is "I discovered something about an NPC." With it, this is "I discovered something about a *friend*." + +**Why this proves the thesis:** Gore says "all knowledge changes the knower." This is the proof. Before this moment, the smuggler lived in a world where their colleagues were trustworthy. After it, they live in a world where anyone could be compromised. Before this moment, the detective lived in a world where the case was abstract. After it, the case has a face they recognize. The knowledge hasn't just changed what they know — it's changed *who they are*. The smuggler is now someone who suspects friends. The detective is now someone who hurts people they like. And neither can go back. + +**Minimum conditions:** At least one NPC per playthrough who the player has positive dialogue interactions with during the first 15-20 minutes AND who is implicated in something the player later discovers. Relationship dynamics (#103) must be at HIGH priority — the positive relationship state is what gives the discovery its weight. Dialogue layers 3 and 4 (#171-172, trust-gated gossip and unprompted disclosure) must be at HIGH priority — these are the systems that build the attachment before it's threatened. Without layers 3-4, the NPC is just someone who said hello. With them, the NPC is someone who *confided in you*. + +--- + +### Moment Architecture Summary + +| Moment | Earliest timing | Systems required | Emotional arc | Minimum for proof | +|--------|----------------|------------------|---------------|-------------------| +| **Recognition Divide** | First 5 minutes | Info boundaries + monologue + character builds | Curiosity -> "my character sees the world differently than I expected" | 5 shared NPCs with dual monologue sets | +| **Absence That Speaks** | Minutes 10-20 | Routine system + absence detection + fog + monologue | Familiarity -> disruption -> anxiety -> "something's wrong" | 2 NPCs with deviation events + absence monologue | +| **Cost of Knowing** | Minutes 20-30 | All social systems + information gain + monologue | Attachment -> discovery -> moral weight -> "what do I do?" | 1 NPC per character with positive rapport + incriminating discovery | + +**The arc across all three moments:** The player starts by discovering how their character sees the world (Recognition Divide). They then discover that the world doesn't always match expectations (Absence That Speaks). Finally, they discover that knowing the truth comes at a personal cost (Cost of Knowing). This is a compressed character arc: innocence -> awareness -> moral complexity. It plays out in 30 minutes. And it plays differently for each character because each character starts from a different "innocence" and arrives at a different "moral complexity." + +--- + +## 3. The Authoring Document: Merging Gore's Dual Interpretation Guide with Character Arc Progression + +Gore proposes a "Dual Interpretation Authoring Guide" — a document that maps shared locations, events, and NPCs with authored monologue and behavioral variations showing how the same reality looks from two different identities. + +I proposed a "Character Arc Progression" — a design document that defines the emotional journey for each character: what pressure curves drive the arc forward, what choice points emerge from systems, what emotional states the monologue should track. + +These are two halves of one document. Let me complicate this by naming the relationship: Gore's guide is the **horizontal axis** (same moment, two interpretations) and my arc is the **vertical axis** (same character, evolving interpretation over time). A complete authoring document needs both. + +### Proposed Document: "Perspective and Arc — v0.1 Authoring Specification" + +**Assigned to:** Gore (thematic framing) + Paula (narrative structure) + Mellanie (authoring execution) + Miri (setting grounding) + +**Contents:** + +#### Part 1: Interpretive Frames (from Gore's Dual Interpretation Guide) + +For each playable character, define: + +| Element | Smuggler | Detective | +|---------|----------|-----------| +| **Core identity** | Colleague, insider, protector of people doing illegal things | Investigator, outsider, pursuer of truth that may hurt people | +| **Interpretive lens** | "Who is this person to me? Are they safe? Do they need me?" | "What is this person doing? Does it fit? What are they hiding?" | +| **Default emotional register** | Warmth (toward allies), anxiety (about exposure), guilt (about the work) | Curiosity (about patterns), obligation (to institution), doubt (about cost of truth) | +| **What they notice first** | Emotional states of people they know. Who's stressed. Who's new. Who's missing. | Behavioral patterns. Deviations from routine. Things that don't fit. | +| **What makes them uncomfortable** | Being unable to protect someone. Suspecting an ally. Loss of trust. | Evidence pointing at someone they like. Institutional pressure. Moral grey areas. | + +#### Part 2: Dual Interpretation Scenes (from Gore's guide) + +For each shared social site, map the key observations that both characters can make and specify the divergent monologue: + +**Example: Logistics Hub — Morning Shift** + +| Observation | Smuggler monologue | Detective monologue | +|-------------|-------------------|---------------------| +| Kael is at his workstation, looking tired | *"The late drops are wearing on him. I should cover his next shift."* | *"He looks tired. Working overtime, or something keeping him up?"* | +| Cargo manifest discrepancy on screen | *"Whoever filed this used the wrong codes. I'll fix it before anyone notices."* | *"Those codes don't match standard format. Someone's editing manifests."* | +| Unknown person talking to supervisor | *"New face. The boss doesn't usually meet people this early. Something's off."* | *"Meeting before shift starts? Nobody on my contact list. Worth noting."* | +| Sari laughing with colleagues | *"Good to see her smiling. She's the one who keeps this place sane."* | *"Popular with the crew. People confide in people they like."* | + +**Minimum coverage:** 5 key observations per shared social site x 3 social sites = 15 dual-interpretation scenes. Each scene produces 2 monologue lines (one per character) = 30 critical monologue lines that prove the thesis. + +#### Part 3: Character Arc Beats (from my Character Arc Progression) + +For each character, define the emotional journey in 3 phases across the 30-minute play session: + +**Smuggler Arc:** + +| Phase | Timing | Emotional state | Monologue tone | What drives the transition | +|-------|--------|----------------|----------------|---------------------------| +| **Routine** | 0-10 min | Comfortable, in control, familiar | Casual, warm, protective. *"Same old shift."* | Player establishes daily pattern — work, talk, observe | +| **Pressure** | 10-20 min | Anxious, watchful, protective | Alert, worried, second-guessing. *"Something's not right."* | Absence detection fires. Routine deviation observed. A colleague behaves differently. | +| **Crisis** | 20-30 min | Torn, afraid, morally weighted | Conflicted, urgent, emotionally loaded. *"I can't pretend I didn't see that."* | Discovery of betrayal, institutional pressure, or ring compromise. The cost of knowing. | + +**Detective Arc:** + +| Phase | Timing | Emotional state | Monologue tone | What drives the transition | +|-------|--------|----------------|----------------|---------------------------| +| **Survey** | 0-10 min | Confident, methodical, observant | Professional, detached, note-taking. *"New assignment. Let's see what we've got."* | Player establishes routine — walk the beat, interview people, observe patterns | +| **Pattern** | 10-20 min | Intrigued, suspicious, focused | Analytical, probing, increasingly certain. *"This doesn't add up."* | Multiple observations accumulate. Absence detection fires. Evidence connects. | +| **Reckoning** | 20-30 min | Reluctant, conflicted, duty-bound | Heavy, questioning, morally uncertain. *"The evidence doesn't care what I want it to say."* | Evidence points at someone the detective likes. Truth threatens community. | + +**Key design constraint:** The arc phases are NOT scripted triggers. They emerge from cumulative exposure to the systems. Phase transitions happen when: +- Enough routine observations have established a baseline (phase 1 -> 2) +- Enough deviations from routine have accumulated (phase 2 -> 3) +- A discovery creates moral stakes (phase 3 onset) + +The monologue's tone shifts should be driven by tracked discovery count, relationship state, and elapsed time — not by "at minute 15, switch to phase 2." The storyteller (#162) can modulate the pacing, but the player's own actions determine when they accumulate enough experience to feel the shift. + +#### Part 4: Monologue Tone Tracking + +A lightweight system that modifies monologue line selection based on accumulated experience: + +| Trigger | Effect on monologue | Example | +|---------|---------------------|---------| +| First visit to a social site | Orientation lines, first impressions | *"So this is the district bar. Busy for a Tuesday."* | +| Return visit (3+) | Familiarity lines, noticing regulars | *"The usual crowd. Except — where's booth three?"* | +| Discovery event | Recontextualization lines | *"I've been walking past this office every day. Now I know what's behind the door."* | +| Relationship milestone | Emotional reflection lines | *"I didn't expect to care what happens to Sari. But I do."* | +| Moral conflict moment | Weight-of-knowledge lines | *"I know too much. Every option has a cost."* | + +This is my Round 1 proposed ticket "Monologue tone progression" (#7) — but now grounded in Gore's thesis. The tone doesn't just progress from confident to uncertain. It progresses from *one reality* (the world as the character assumed it) to *another reality* (the world as the character now knows it). The progression IS the thesis: who you are determines what is real, and what you discover determines who you become. + +#### Part 5: Thematic Content Notes (from Gore's additional claims) + +Specific guidance for Mellanie's content authoring: + +1. **Surveillance/privacy tension:** The detective's observation tools are the same tools the state uses. The smuggler's evasion tactics are the same tools dissidents use. Neither character is innocent. Include 2-3 monologue lines per character that register awareness of this parallel. + +2. **The quiet life validation:** At least 3 unentangled NPCs should have monologue lines that make the player reflect on their contentment. *"She seems happy here. Simple life. I used to think that was boring."* These lines only fire if the player has accumulated enough stressful discoveries — the quiet life looks different once you've seen the alternative. + +3. **The cost of knowing:** Every significant discovery should come with a monologue line that acknowledges the emotional cost. Not melodrama — just a beat of recognition. *"Another thing I can't unknow."* This plants Gore's seed about knowledge changing the knower. + +4. **Backup reference (D-008 seed):** 2-3 lines per character referencing their memory backup schedule. *"Last backup was... two months ago? A lot's changed since then."* This connects the player's accumulated experience to the character's sense of self. Losing it all would be losing *who they've become*. + +--- + +## 4. Does Narrative Depth Survive Seed Variation? + +Nigel raises the critical replayability concern: seed variation (#178) is LOW priority, but without it, the replay ceiling drops to 2 playthroughs. His question, applied to my domain: can the same emotional arcs work with different NPC configurations? + +**The honest truth is: yes, but only if we author for roles, not individuals.** + +Let me explain the tension and the resolution. + +### The Tension + +The three moments I described above depend on *specific* emotional relationships. Moment 3 (The Cost of Knowing) requires the player to have built rapport with an NPC who is later implicated. If seed variation shuffles which NPC fills which role, the rapport needs to attach to *whoever fills the role*, not to a specific named character. + +This creates a design fork: + +**Option A: Author for specific NPCs.** Create "Kael" as a fully realized character with specific monologue, specific personality, specific arc. Every playthrough features Kael. Deep, specific, but identical across seeds. Replay ceiling: 2 (one per character). + +**Option B: Author for roles.** Create "the colleague who's in too deep" as a role archetype with monologue templates, personality ranges, and arc structures. Each seed fills the role with a different NPC. Broader, more replayable, but potentially thinner. + +### The Resolution + +**We do both. And here's how.** + +The NPC model (D-024) already separates role from individual. A social site template defines roles (bar owner, regular, smuggling contact). The NPC generation pipeline (#92) fills roles with generated individuals. The 10-axis model gives each individual variation. + +The narrative authoring should work at three layers: + +| Layer | What it is | Who writes it | Seed-dependent? | +|-------|-----------|---------------|-----------------| +| **Role archetype** | "The colleague who's in too deep" — arc structure, emotional beats, monologue templates with [NAME] slots | Paula + Gore (design), Mellanie (authoring) | No — same structure every seed | +| **NPC instantiation** | Specific name, personality traits, tell behaviors, relationship starting values | NPC generation pipeline (#92) | Yes — varies per seed | +| **Trait-modified delivery** | Monologue templates reshaped by personality traits | Trait modifier system (#173) | Yes — same archetype, different voice | + +**Example across two seeds:** + +| Element | Seed A | Seed B | +|---------|--------|--------| +| Role: "colleague in too deep" | **Kael** — anxious personality, tell: fidgets when lying, contented before pressure | **Ren** — stoic personality, tell: avoids eye contact, restless before pressure | +| Monologue (smuggler, concern phase) | *"Kael's been fidgeting all morning. He's never been good at hiding things."* | *"Ren won't look at me. That's not like her. Something's wrong."* | +| Monologue (detective, suspicion phase) | *"Subject is exhibiting anxiety indicators. Fidgeting, distracted. Worth monitoring."* | *"Subject maintains composure but avoids direct eye contact. Trained or guilty?"* | + +The emotional arc is identical: concern/suspicion about a colleague. The surface delivery varies with the individual. The player experiences the same narrative depth but with different characters, different tells, and different specific observations. + +### What This Requires + +1. **Role archetype authoring** as a distinct content layer — not specific NPC monologue, but archetype monologue with trait modification. This is a new content specification for the authoring guide (Part 1 of the merged document). + +2. **Trait modifier system (#173) promoted to HIGH.** Currently medium. Without trait modifiers, role archetypes produce identical monologue regardless of which NPC fills the role. Trait modifiers are what make Kael-in-this-role feel different from Ren-in-this-role. + +3. **Tell variation per seed** — Nigel's proposed ticket. Tells must be seed-dependent so that the *observable evidence* varies even when the underlying role structure doesn't. Hesitation means guilt in one seed; it's a personality trait in another. + +4. **Monologue line pools (#120) authored with [ROLE] tags, not [NPC_NAME] tags.** The generation pipeline maps role to NPC, and the monologue system substitutes the specific NPC's name and traits. + +### Does This Weaken Narrative Depth? + +**No — if anything, it strengthens it.** Here's why. + +The risk of specific-NPC authoring is that the second playthrough with the same character and the same seed is a walkthrough guide. You know exactly who's guilty, who to trust, who to watch. Dramatic irony (Nigel's point) helps on the cross-character playthrough — but on the same-character replay, there's no surprise left. + +Role-archetype authoring with seed-dependent instantiation means the player's *structural knowledge* transfers (I know the colleague-in-too-deep role exists) but their *specific knowledge* doesn't (I don't know which colleague it is). This is exactly the anti-metagaming dynamic Nigel and D-029 envision. The player who played smuggler in seed A arrives at seed B thinking they know the pattern — and they're wrong about the specifics while being right about the structure. That's a *richer* replay experience than either pure repetition or pure randomness. + +### Nigel's Concern Addressed + +**Narrative depth survives seed variation if:** +1. We author at the role-archetype level, not the individual level +2. Trait modifiers (#173) reshape delivery per NPC +3. Tell variation per seed prevents pattern-learning across playthroughs +4. The emotional arc structure is seed-independent; the specific characters within it are seed-dependent + +**Narrative depth FAILS seed variation if:** +1. We author specific monologue for specific named NPCs with no role abstraction +2. Tells are fixed (hesitation always means guilt regardless of seed) +3. Triangle configurations are too rigid (the same three roles always form the same triangle type) + +The honest recommendation: **promote #178 (seed-based variation) to HIGH**, as Nigel proposes, AND ensure the authoring specification uses role-archetype templates with trait modification, not NPC-specific content. + +--- + +## 5. Consolidated Priority Promotions and New Tickets + +Let me consolidate my Round 1 proposals with Gore's recommendations, resolving overlaps and establishing a minimal narrative investment for v0.1. + +### What Gore and I Agree On + +We independently converged on: + +1. **Claim 5 is highest risk.** My "HIGH" risk rating and Gore's "MEDIUM-HIGH" reflect the same diagnosis: mechanical divergence is covered; narrative/interpretive divergence is not. + +2. **Monologue is the MVP.** My "single highest-ROI narrative decision" and Gore's "content and authoring problem, not a systems problem" are the same conclusion from different angles. The systems are right. The content guidance is missing. + +3. **Same observation, different meaning.** My "interpretive asymmetry" and Gore's "recontextualization moment" describe the same phenomenon. We need authored content where the same NPC behavior produces contradictory-but-coherent monologue from each character. + +4. **Character voice (#121) must be interpretive, not tonal.** Gore explicitly calls this out. I flagged the gap between "different facts" and "different feelings." Same fix: #121 needs to be scoped as interpretive framing, not just voice variation. + +5. **Mundane triangles need authorial investment.** Gore says treating them as noise is "thematically backward." I say they're "where emotional payoff matters most." Same point: the 50% mundane population isn't camouflage — it's the thesis. + +### Consolidated Priority Promotions + +| Ticket | Current | Recommended | Paula's rationale | Gore's rationale | Combined case | +|--------|---------|-------------|-------------------|------------------|---------------| +| **#103 Relationship dynamics** | Medium | **High** | Required for Moment 3 (Cost of Knowing), NPC attachment | Contentment expression requires dynamic relationships | Without this, no NPC feels like a person who changes. Blocks the emotional payload of all three moments. | +| **#105 Tolerance thresholds** | Medium | **High** | Triangle escalation, observation chain | Triangle activation is how drama HAPPENS | The trigger for observable social events. Without it, triangles are backstory, not drama. | +| **#121 Character voice variation** | Medium | **High** | Interpretive framing is the thesis proof | "Interpretive framing, not just tone" | This IS the "who you are determines what is real" system. Mechanically small (monologue tag filtering), narratively enormous. | +| **#171 Trust-gated gossip** | Medium | **High** | Progressive revelation, triangle discovery | Mundane triangles need discoverable texture | Players discover triangles through gossip. Without layer 3, social life is surface-level greetings. | +| **#172 Unprompted disclosure** | Medium | **High** | NPC-initiated narrative moments, off-screen narration | NPCs must feel like they have agenda | The system that makes NPCs into *people* rather than dialogue dispensers. The bartender who says "You missed it — Sario and the boss had it out yesterday" without being asked. | +| **#173 Trait modifier system** | Medium | **High** | Required for seed-variation narrative depth (see section 4) | Implicit — needed for "different realities" to work across seeds | Role archetypes without trait modification produce identical delivery regardless of NPC. This is the system that makes each seed's NPCs feel distinct. | +| **#162 Storyteller activation** | Low | **Medium** | 30-min arc needs escalation curve | Not explicitly flagged but implied by "contamination" | Even a timer-based version gives the session shape. Without it, daily life has no crescendo. Ozzie's diagnosis is correct: without a storyteller, the player wanders until bored. | +| **#178 Seed-based variation** | Low | **High** | Role-archetype authoring depends on seed generating different NPCs for same roles | Not explicitly flagged | Nigel's case is airtight. Without this, replay ceiling = 2. With it, the same role-archetype monologue produces different specific experiences per seed. | + +### Consolidated New Tickets + +Merging my Round 1 proposals with Gore's recommendation and insights from Ozzie, Gestalt, and Nigel: + +| # | Title | Priority | Rationale | Convergence | +|---|-------|----------|-----------|-------------| +| 1 | **Identity-driven monologue interpretation** | High | Monologue queries character's interpretive frame (cares about, fears, responsible for), not just knowledge state. Connects #119 (monologue generation) to #180-181 (character builds) through identity, not just data. | Revised from my R1 "Knowledge-aware monologue integration" per Gore's thesis. Subsumes the "what" and adds the "why." | +| 2 | **Absence detection / routine deviation detection** | High | Compares character's known NPC routine data against observed reality. Flags discrepancies. Feeds into monologue system AND observation pipeline. | My "absence detection" + Ozzie's "routine deviation detection" are the same system. One ticket, two functions: mechanical (core detective loop) and narrative (tension generator). | +| 3 | **Triangle escalation and resolution** | High | Periodic state updates push triangle tensions toward breaking points. Observable events when triangles enter crisis. Consequences when triangles resolve. | My R1 proposal. Endorsed by Ozzie ("triangle escalation events"), Gestalt ("triangle activation mechanics"). Universal agreement this is missing. | +| 4 | **Player-action social propagation** | High | Actions toward one NPC ripple through relationship graph. First-order strong/immediate, second-order weaker/delayed. | My R1 proposal. Gestalt flags the feedback loop gap. Gore's "cost of knowing" requires that knowledge-actions have social consequences. | +| 5 | **Tell visual/behavioral expression** | High | Defines how NPC tells manifest in top-down renderer. Movement hesitation, routine deviation markers, interaction changes. | My R1 proposal. Ozzie and Gestalt both flag this. Without visual tells, the observation chain has no starting point. | +| 6 | **Perspective and Arc authoring specification** | High | The merged document (section 3 above). Interpretive frames, dual interpretation scenes, character arc beats, monologue tone tracking, thematic content notes. | Merges Gore's "Dual Interpretation Authoring Guide" + my "Character arc progression." Assigned to Gore + Paula + Mellanie + Miri. | +| 7 | **Monologue tone progression** | Medium | Track cumulative discoveries and relationship changes; modify monologue line selection from routine to uncertain/questioning. | My R1 proposal, now grounded in the arc structure from the merged authoring spec. | + +### Tickets I'm Deprioritizing (from my Round 1 list) + +- **"Monologue state progression" (was medium)** — absorbed into ticket #7 above and the authoring specification. +- **"Consequence propagation" and "player-action social propagation"** — merged into one ticket (#4 above). + +### What's NOT in This List (and Why) + +Gore identifies several content notes (surveillance tension, backup references, cost-of-knowing acknowledgment) that don't need tickets — they need **authoring guidance** in the Perspective and Arc specification. These are Mellanie's content requirements, not system requirements. The specification (ticket #6) is where they live. + +--- + +## Final Assessment: The Minimal Narrative Investment for v0.1 + +Let me be honest about what the v0.1 needs to prove Gore's thesis. + +**The thesis:** "Who you are determines what is real." + +**The proof:** Two players describing the same 30-minute play session should sound like they played different games — not because they saw different content, but because they *interpreted the same content through different identities*. + +**The minimal narrative investment:** + +| Investment | What it produces | Cost | Impact | +|------------|-----------------|------|--------| +| **Identity-driven monologue** (ticket #1) | The smuggler and detective see the same world and think different things about it | System: connect monologue to character build interpretive frames. Content: 30 dual-interpretation monologue lines (15 observations x 2 characters). | **Proves the thesis directly.** Without this, both characters think the same thoughts with different facts. | +| **Absence detection** (ticket #2) | Characters notice when the world doesn't match expectations, creating tension from knowledge gaps | System: compare expected vs observed NPC presence. Content: 10-15 absence monologue lines per character. | **Creates Moment 2.** The detective game starts here. | +| **Relationship dynamics promoted** (#103) | NPCs change off-screen, creating discoverable consequences | System: already designed, needs priority promotion | **Enables Moment 3.** Without dynamic relationships, attachment can't be threatened. | +| **Trust-gated gossip promoted** (#171) | NPCs reveal social texture as trust builds | System: already designed, needs priority promotion. Content: 10-15 gossip lines per template. | **Sustains 30 minutes.** Without gossip, daily life is hello-goodbye. | +| **Perspective and Arc spec** (ticket #6) | Authoring guide ensuring all content serves the thesis | Document: ~2,000 words of authoring specification | **Multiplies all other investments.** Ensures Mellanie's content packs are authored with dual interpretation and arc progression in mind. | + +**Total content cost for narrative proof:** ~80-100 critical monologue lines (dual-interpretation + absence + arc progression), plus the authoring specification. This is a bounded, achievable writing task. The systems cost is modest — monologue integration with character builds, absence detection, and priority promotions of already-designed systems. + +**What happens if we skip this:** The systems work. The information boundaries filter correctly. The fog renders. The triangles generate. Two characters see different data. And the player says: "Yeah, the smuggler knew different stuff than the detective. Neat mechanic." That's a tech demo. That's not a proof of concept. The proof is when the player says: "The smuggler and the detective live in different *worlds*. Same station, same people, different reality." That's the thesis. That's what the monologue investment buys. + +The honest truth is that the narrative investment I'm describing is small relative to the total v0.1 effort — maybe 5-8% of the content work. But it's load-bearing for 100% of the thesis proof. Every system the team builds is infrastructure for this moment. And without this specific content investment, the infrastructure has nothing to carry. + +--- + +*Paula out. The monologue is the cheapest system and the most important investment. Build the interpretive layer, and every other system sings.* diff --git a/docs/workshops/v01-gap-analysis/round2-tyre.md b/docs/workshops/v01-gap-analysis/round2-tyre.md new file mode 100644 index 000000000..ef22a2d3b --- /dev/null +++ b/docs/workshops/v01-gap-analysis/round2-tyre.md @@ -0,0 +1,550 @@ +# Workshop Round 2 — Tyre (Technical Architect) + +**Tracks:** 3 + 4 (Cross-pollination and synthesis) +**Date:** 2026-02-11 + +--- + +## 1. GUT vs gdUnit4 — Final Recommendation + +*I'm changing my mind. Hoshe is right.* + +I recommended GUT in Round 1 based on maturity, documentation breadth, community size, and Claude Code training data familiarity. Those are real advantages in a general context. But Hoshe's comparison table forced me to reconsider for THIS project's specific constraints: agent-driven development, headless execution, and structured output parsing. + +### Where Hoshe's arguments win + +| My Round 1 argument for GUT | Hoshe's counter | My assessment | +|------------------------------|-----------------|---------------| +| 8+ years maturity | gdUnit4 has been around since Godot 3, maintained by an organization (godot-gdunit-labs), not a solo developer | **Hoshe wins.** Bus factor matters for a multi-year project. bitwes is a single maintainer. | +| More documentation | gdUnit4 docs are comprehensive for what we need. Our Godot tests are thin by design (D-020: client is a pure renderer) | **Draw.** We're not writing complex GDScript tests — documentation depth is less critical. | +| Larger community | Irrelevant if headless execution has known issues | **Hoshe wins on the specifics.** GUT issue #491 (headless mode problems) is a real concern for agent-driven TDD. | +| More AI training data | Claude Code can work with gdUnit4's docs and examples. This was my weakest argument. | **Weak argument. Withdrawing it.** | +| Simpler, less magic | gdUnit4's extra features (GdUnitSceneRunner, 13 assertion types) are things we'll actually use for dialogue UI (#174) and fog overlay (#113) testing | **Hoshe wins.** The "extra complexity" is useful complexity. | + +### What clinches it + +**JSON output.** This is the decisive factor. Our agents consume test results. gdUnit4 produces JSON natively. GUT produces console text that needs parsing. In an agent-driven workflow, structured output isn't a nice-to-have — it's how agents understand what broke and where. Hoshe's proposed JSON summary format (section 5 of their analysis) maps directly to gdUnit4's output, no post-processing tool needed. + +**Stable headless support.** If agents can't reliably run `godot --headless` tests without hitting GUT-specific headless bugs, the entire Godot test infrastructure is unreliable. gdUnit4's `GdUnitCmdTool` is designed for CLI/headless from the start. + +**Scene runner with input simulation.** `GdUnitSceneRunner` gives us time control and input simulation in scene tests. When Stig builds the dialogue UI (#174) or Stig tests the fog overlay rendering parameters (#113), scene-level tests with simulated inputs are exactly what's needed. GUT can do this, but gdUnit4's scene runner is purpose-built. + +### Final recommendation: gdUnit4 + +```bash +# Agent invocation — clean, structured +godot --headless --path client/ \ + -s addons/gdUnit4/bin/GdUnitCmdTool.gd \ + --test-suite "${1:-test/}" \ + --report-format json +``` + +I'm being honest: I was wrong in Round 1, and Hoshe's argument is better. For general Godot projects, GUT is still a fine choice. For agent-driven development with headless execution requirements, gdUnit4 is the right tool. + +--- + +## 2. Hoshe's CauseChain Proposal — Reaction + +**Verdict: Accept. This is a production feature, not test pollution.** + +Hoshe proposes adding a `CauseChain` component to information gain events — every piece of new information tracks HOW it was learned. The chain traces back through perception events (`Cause::VisualObservation`, `Cause::AudioObservation`, `Cause::DialogueReveal`) and flags scripted reveals (`Cause::ScriptedReveal`). Criterion 4 (#199) can then assert that discoveries are system-driven by checking that no chain contains `Cause::ScriptedReveal`. + +### Does it violate "no test pollution"? + +No. Here's my analysis against the five production code constraints I defined in Round 1: + +| Constraint | CauseChain assessment | +|-----------|----------------------| +| No conditional compilation that changes production behavior | CauseChain is always present, not `#[cfg(test)]` | PASS | +| No `pub` visibility escalation for tests | CauseChain is a public ECS component that serves production needs | PASS | +| No test-specific parameters on production functions | CauseChain is attached by the information system, not injected for testing | PASS | +| Public API is the test surface | CauseChain IS public API — it's queryable through standard ECS queries | PASS | +| ECS World setup is the test fixture | Tests query CauseChain through normal component queries, no special hooks | PASS | + +### Why it's a production feature that HAPPENS to help testing + +Reading across ALL the Round 1 analyses, the design team converged independently on the same need: + +- **Gestalt (Track 1, Claim 4):** "No observation event pipeline — the SPINE of the game is spread across 4 epics with no connecting tissue." CauseChain IS the connecting tissue. +- **Ozzie (Track 1, Claim 3):** "NOTICING THAT AN NPC BROKE THEIR ROUTINE IS THE CORE GAMEPLAY LOOP AND IT'S NOT A TICKET." CauseChain tracks how that routine deviation was detected. +- **Paula (Track 1, Claim 4):** "The observe->notice->follow->discover chain... Each link has ticket coverage. The question is whether the chain is CONNECTED." CauseChain connects the links. +- **Gore (Track 1, Claim 4):** "The game rewards you for watching people... observation is ethically loaded." CauseChain enables the monologue system to comment on HOW information was gained. + +CauseChain serves at least four production purposes: + +1. **Monologue integration:** The monologue system needs to know HOW information was learned to generate character-specific commentary. "I saw..." vs "I overheard..." vs "She told me..." — the cause chain determines monologue voice. +2. **Knowledge journal:** When the player reviews their information inventory (#89), the journal can show provenance: "Learned by observing Kael at the loading bay, Day 3, 11pm." +3. **Debugging/storytelling:** When a chain of events produces an unexpected outcome, developers can trace causality. This is the ECS equivalent of distributed tracing. +4. **Success criteria validation:** Criterion 4 (#199) can programmatically verify that discoveries emerge from systems, not scripts. + +### Implementation sketch + +```rust +/// How a piece of information was gained +#[derive(Component, Debug, Clone)] +pub struct CauseChain { + pub steps: Vec, +} + +#[derive(Debug, Clone)] +pub struct CauseStep { + pub cause: Cause, + pub tick: u64, + pub entity: Option, // the entity involved +} + +#[derive(Debug, Clone, PartialEq)] +pub enum Cause { + VisualObservation, // Saw it happen (perception system) + AudioObservation, // Heard it (sound system) + DialogueReveal, // NPC told you (dialogue system) + InferredFromPattern, // Character deduced it (monologue system) + InstitutionalAccess, // Case file, database, etc. (access tier) + StartingKnowledge, // Character knew at game start + // For criterion 4 validation: + ScriptedReveal, // Hard-coded trigger (should NOT appear in v0.1) +} +``` + +**Effort:** Small — it's a component definition + attachment logic in the information system. Maybe 1-2 days of work. **But** it should be designed alongside the information inventory (#89), not as a separate ticket. Same component model, same query patterns. + +### Recommendation + +Add CauseChain to the information system design. Not as a testing feature — as a production component that the monologue system, knowledge journal, and criterion validation all consume. Hoshe identified the right architecture; the design team's Round 1 analyses independently confirmed the need. + +--- + +## 3. Three-Layer IPC Testing — Merged Architecture + +Hoshe proposes three layers: fixture-based (fast), mock subprocess (medium), real subprocess (slow). My Round 1 said "real IPC, not mocks." These aren't contradictory — they're complementary. Hoshe's layers test DIFFERENT things at DIFFERENT speeds. + +### Where we agree completely + +- Real subprocess integration tests are the ground truth (my position, Hoshe's Layer 3) +- Serialization roundtrip tests should be fast and independent (Hoshe's Layer 1) +- Bash wrapper scripts for agent invocation (both proposed this) +- `cargo-nextest` for Rust test execution (both proposed this) +- Flaky tests are bugs, not tolerated (both stated this) + +### Where Hoshe extends my proposal + +My Round 1 had two test layers: unit tests (internal) and integration tests (real IPC). Hoshe inserts a middle layer: **protocol sequence testing** with a mock subprocess. This tests the GDScript `LocalBridge` implementation's state machine (handshake → tick loop → error recovery) without needing the full simulation. + +*cracks knuckles* + +Let me be honest about what this middle layer buys us. The real benefit is **speed and isolation for client-side protocol development**. When Oscar (networking) is building the LocalBridge in GDScript, they need to test protocol state transitions without waiting for the Rust simulation to compile and start. A mock subprocess that sends predetermined sequences lets Oscar iterate on the GDScript side independently. That's not test pollution — that's development velocity. + +The mock subprocess is also where we test error recovery: what happens when the simulation sends malformed MessagePack? When the connection drops? When the handshake times out? These are adversarial conditions that are hard to trigger reliably with the real simulation but trivial to script with a mock. + +### Final merged test architecture + +``` +TEST LAYERS +=========== + +Layer 1 — Serialization Fixtures (fast, every edit cycle) +├── Rust: ObserverSnapshot → MessagePack → ObserverSnapshot roundtrip +├── Rust: PlayerInput → MessagePack → PlayerInput roundtrip +├── GDScript: MessagePack bytes → Dictionary → verify field values +├── Cross-language: Rust writes fixture files (.msgpack), GDScript reads + verifies +└── Target: < 1 second total + +Layer 2 — Protocol State Machine (medium, every PR) +├── Mock subprocess sends predetermined message sequences +├── Tests handshake, tick loop, snapshot delivery, input receipt +├── Tests error conditions: malformed data, timeout, disconnect, reconnect +├── Tests GDScript LocalBridge without real simulation +└── Target: < 10 seconds total + +Layer 3 — Real Integration (slow, daily / pre-merge) +├── Spawns actual simulation binary as subprocess +├── Sends real PlayerInput, receives real ObserverSnapshot +├── Tests: movement, perception filtering, NPC routines, info boundaries +├── Uses test fixtures: small map (10x10), minimal NPCs (3-5) +├── Deterministic: same seed + inputs = same outputs +└── Target: < 60 seconds total + + +SIMULATION-ONLY TESTS (no IPC involved) +======================================= + +Unit tests — #[cfg(test)] inline +├── Shadowcasting algorithm edge cases +├── Pathfinding heuristics +├── Perception query filtering +├── Collision detection logic +├── Time-to-tick conversion +└── Target: < 5 seconds for full suite + +Integration tests — tests/ directory +├── Full tick loop: spawn world → add entities → tick N → assert state +├── Observer snapshot generation and filtering +├── NPC behavior: routine execution, mood changes, relationship dynamics +├── Information boundary enforcement +├── CauseChain propagation through observation chain +└── Target: < 30 seconds for full suite + + +CLIENT-ONLY TESTS (Godot, no simulation) +========================================= + +Unit tests — gdUnit4 +├── MessagePack deserialization +├── ObserverSnapshot → scene tree mapping +├── Fog overlay parameter calculation +├── UI widget state from HUD data +├── Input capture → PlayerInput serialization +└── Target: < 5 seconds for full suite + +Scene tests — gdUnit4 with GdUnitSceneRunner +├── Dialogue UI lifecycle (#174) +├── Fog rendering parameter application (#113) +├── Monologue display and fading (#122) +└── Target: < 10 seconds for full suite + + +WRAPPER SCRIPTS (test/ directory) +================================== + +test/run-rust # cargo nextest run (all Rust unit + integration) +test/run-rust --filter X # filtered Rust tests +test/run-godot # gdUnit4 headless (all Godot tests) +test/run-ipc-fixtures # Layer 1 only (fast) +test/run-ipc-protocol # Layers 1-2 (medium) +test/run-ipc-integration # All three layers (slow) +test/run-all # Everything, sequential, combined report +``` + +### Test output: JSON summary from all runners + +Both Hoshe and I agree on structured output. The wrapper scripts produce a consistent JSON summary regardless of underlying framework: + +```json +{ + "suite": "simulation::perception", + "runner": "cargo-nextest", + "duration_ms": 247, + "total": 15, + "passed": 14, + "failed": 1, + "failures": [ + { + "test": "wall_blocks_vision_diagonal", + "file": "simulation/src/perception/shadowcast.rs", + "line": 142, + "message": "assertion failed: tile (3,3) should not be visible" + } + ] +} +``` + +For Rust, `cargo-nextest` outputs structured results that can be piped through a small formatter. For Godot, gdUnit4's native JSON output is already in a usable format. The wrapper scripts normalize both into the same schema. + +### Test fixtures directory + +``` +test/ + fixtures/ + maps/ + small_10x10.bin # Pre-generated test map + corridor_20x5.bin # Linear corridor for pathfinding tests + sightline_test.bin # Known sightline geometry + npcs/ + minimal_3.json # 3 NPCs with known configs + triangle_test.json # 3 NPCs forming a triangle + routine_test.json # NPCs with known daily routines + protocol/ + snapshot_basic.msgpack # Known-good ObserverSnapshot + input_move.msgpack # Known-good PlayerInput + malformed.msgpack # Intentionally broken data +``` + +--- + +## 4. Design Team Findings — Impact on Test Priority + +### The five hard blockers all agents converge on + +Reading across Gestalt, Ozzie, Paula, Nigel, and Gore, the design team independently converged on five systems that are missing or underspecified: + +| Hard Blocker | Who flagged it | Test implications | +|---|---|---| +| **Collision detection** | Tyre (Round 1), Gestalt | Highly unit-testable: `can_move_to(tile) -> bool`. Write tests alongside implementation. | +| **Pathfinding** | Tyre (Round 1), Gestalt | Highly unit-testable: A* algorithm, path validity, obstacle avoidance. Integration-testable: NPC follows path over N ticks. | +| **Time system** (Q-009) | Tyre (Round 1), Gestalt, Ozzie | Unit-testable: tick-to-time conversion, day-phase transitions. Integration-testable: routine triggers at correct game-time. | +| **Interaction dispatcher** | Tyre (Round 1), Gestalt | Integration-testable: player presses Interact near NPC → dialogue system activates. | +| **Opening hook** | Gestalt, Ozzie | Content validation: monologue fires appropriate lines in first 30 seconds. Tests depend on content packs existing. | + +### The monologue system as critical integration point + +Every single design agent flagged the monologue system as THE critical integration point: + +- **Gestalt:** "No observation event pipeline — the SPINE of the game" +- **Ozzie:** "The observation event pipeline and routine deviation detection I'm asking for are the GLUE between existing systems" +- **Paula:** "The monologue system is the MVP of narrative delivery" +- **Gore:** "Every gap I've identified routes through the monologue system" + +This has a direct impact on test priority. The monologue system (#119-122) sits at the intersection of perception, information boundaries, NPC state, and character knowledge. It's the system where integration failures are most likely and most damaging. **The first integration tests should exercise the monologue pipeline.** + +### Revised test priority ordering + +My Round 1 test priority was correct for infrastructure, but the design team's findings add content-integration testing as a priority: + +**Phase 1: Foundation (Sprint 1-2)** +1. Confirm testability decisions (#214) — this workshop +2. Set up `cargo-nextest`, gdUnit4, and `test/run-*` scripts +3. Write first unit tests alongside collision and pathfinding implementation +4. Write first integration test alongside #81 (E2E connection test) + +**Phase 2: System integration (Sprint 3-4)** +5. Monologue pipeline integration test: perception → event → line selection → snapshot +6. Information boundary negative tests: "entity X CANNOT see component Y" (Hoshe's proposal — this is the highest-value integration test in the entire project) +7. IPC Layer 1 + 2 tests alongside bridge implementation (#78, #79) +8. Time system tests alongside time system implementation (#25) + +**Phase 3: Content validation (Sprint 5+)** +9. CauseChain verification for observation chain (criterion 4) +10. Divergent snapshot tests (criterion 2): smuggler vs detective on same seed +11. IPC Layer 3 real integration tests +12. Content pack regression tests via line previewer (#193) + +### Key insight: test the monologue pipeline early + +The monologue system receives events from at least 5 other systems (perception, information boundaries, NPC routines, relationship state, tells). An integration test that exercises this pipeline end-to-end is the single highest-value test we can write, because if monologue integration fails, every concept proof claim is at risk. + +```rust +// This test exercises: perception → event → CauseChain → monologue trigger +#[test] +fn npc_routine_deviation_triggers_monologue_event() { + let mut sim = SimulationBuilder::new() + .with_seed(42) + .with_test_map(20, 20) + .with_player_at(10, 10) + .with_npc("kael", Position(5, 5), routine_morning_shift()) + .with_game_time(23, 0) // 11pm — Kael should NOT be at work + .build(); + + // Place Kael in player's vision at unusual time + sim.set_npc_position("kael", Position(10, 11)); + + sim.tick(); + + let snapshot = sim.observer_snapshot(sim.player_entity()); + + // Monologue should fire: character noticed routine deviation + assert!(snapshot.monologue_events.iter().any(|e| + e.trigger == MonologueTrigger::RoutineDeviation + ), "No monologue event for NPC seen outside routine hours"); + + // CauseChain should trace to visual observation + let info_events = sim.query_information_events(sim.player_entity()); + assert!(info_events.iter().any(|e| + e.cause_chain.steps[0].cause == Cause::VisualObservation + ), "Observation should be system-driven, not scripted"); +} +``` + +This single test exercises collision (NPC placement), perception (can the player see Kael?), time system (is it outside routine hours?), routine system (what's Kael's expected schedule?), monologue generation (fire a deviation event), and CauseChain (track how the info was gained). If this test passes, we've proven the SPINE that every design agent asked for. + +--- + +## 5. FINAL Testability Decisions for Ticket #214 + +These are the decisions I'm proposing for team confirmation. Changes from Round 1 are marked. + +### Decision 1: Rust test organization = Hybrid (UNCHANGED) + +- `#[cfg(test)]` for unit tests inside modules (algorithm internals, pure functions) +- `tests/` directory for integration tests (full tick loop, multi-system interaction) +- Both run via `cargo nextest run` + +**Hoshe agrees. No dissent.** + +### Decision 2: Godot test framework = gdUnit4 (CHANGED from GUT) + +- Install gdUnit4 as addon in client project +- Headless execution via `godot --headless` + `GdUnitCmdTool` +- JSON output format for agent consumption +- `GdUnitSceneRunner` for scene lifecycle tests (dialogue UI, fog rendering) +- Minimal initial tests, expand with UI complexity + +**Changed because:** Hoshe's comparison demonstrated that gdUnit4's CLI interface, JSON output, scene runner, headless stability, and organizational maintenance are better fits for our agent-driven development workflow. See section 1 for full rationale. + +### Decision 3: IPC testing = Three-layer architecture (EXTENDED from "real IPC") + +- **Layer 1 — Fixture-based:** Serialization roundtrip tests, cross-language verification. Fast, every edit cycle. +- **Layer 2 — Protocol state machine:** Mock subprocess, tests handshake/error/recovery. Medium speed, every PR. +- **Layer 3 — Real integration:** Actual simulation binary, real protocol. Slow, daily/pre-merge. +- Mock bridge for client-side unit tests (GDScript LocalBridge without real simulation) + +**Extended because:** Hoshe's three-layer approach adds fast feedback for serialization changes and protocol state machine testing without contradicting my "real IPC for integration truth" position. The layers are complementary, not competing. See section 3 for merged architecture. + +### Decision 4: Production code constraints (UNCHANGED + CAUSECHAIN ENDORSED) + +- No conditional compilation that changes production behavior +- No `pub` visibility escalation solely for tests +- No test-specific parameters on production functions +- Public API is the test surface — if untestable through public API, the API boundary is wrong +- ECS World setup replaces mock injection +- Trait boundaries (`SimBridge`) are natural test seams +- **CauseChain is a production component, not test pollution** — serves monologue integration, knowledge journal, debugging, and criterion validation + +**CauseChain endorsed because:** Hoshe's proposal aligns with what every design agent independently flagged as a need: tracking HOW information was gained through the observation chain. It's the ECS equivalent of distributed tracing — a production debugging/integration feature that tests can also leverage. See section 2 for analysis. + +### Decision 5: Test runner tooling (UNCHANGED) + +- `cargo-nextest` for Rust (parallel execution, isolated processes, structured output) +- gdUnit4 for Godot (JSON output, scene runner, stable headless) +- Bash wrapper scripts in `test/` directory, whitelistable for Claude Code agents +- Each script: exit code 0/non-zero, structured stdout, accepts filter arguments, no interactive input + +### Decision 6: Test output format = JSON summary (MERGED) + +- Rust: `cargo-nextest` structured output, normalized to JSON by wrapper script +- Godot: gdUnit4 native JSON output +- Integration: stdout + exit code + JSON summary +- JUnit XML as secondary format for future CI integration +- All wrappers produce consistent JSON schema (suite, total, passed, failed, failures array) + +**Merged because:** Both Hoshe and I converged on JSON as the agent consumption format and JUnit XML as the CI format. gdUnit4's native JSON output eliminates the need for a separate formatter tool on the Godot side. + +### Decision 7: Deterministic replay promotion (NEW — from Hoshe) + +- **Promote #201 (Deterministic replay system) from HIGH to CRITICAL** +- Without deterministic replay, sync tests (#211) and divergence tests (#197) are impossible +- The simulation MUST consume time, randomness, and player input exclusively through injectable resources: `SimulationTime`, `SimRng` (seeded from world seed), `InputQueue` +- No `std::time::Instant`, no `rand::thread_rng()` — everything through resources +- This is a production architecture requirement (D-010 principle 4), not test infrastructure + +**Hoshe is right that #201 should be CRITICAL.** Determinism is not just a testing concern — it's a core architectural principle (D-010). If the simulation isn't deterministic, the replay system can't work, the save system can't verify correctness, and cross-seed variation (#178) can't be validated. + +### Decision 8: Test priority alignment with hard blockers (NEW — from design team) + +- Test infrastructure must be ready for the first hard blocker implementations: collision, pathfinding, time system +- Monologue pipeline integration test is the highest-value cross-system test — write it as soon as monologue and perception systems exist +- Information boundary negative tests are the second highest-value — verify that information DOESN'T leak + +### Still needs discussion (deferred beyond #214) + +- **Performance benchmarks (#204):** Define baselines: tick budget (ms per tick), entity count targets, serialization throughput. Not urgent for v0.1 with 25 NPCs. +- **Full playthrough automation (#212):** Scope to smoke tests only for v0.1. Full automation is premature. Agree with Hoshe's assessment. +- **Rendering verification (#208):** Demote to LOW for v0.1 — headless Godot can't meaningfully verify visual output. Agree with Hoshe. + +--- + +## 6. FINAL New Technical Tickets — Merged and Deduplicated + +I've merged my Round 1 proposals with Hoshe's proposals and cross-referenced against the design team's findings. Duplicates eliminated, related tickets grouped. + +### Hard Blocker Tickets (v0.1 cannot ship without these) + +| # | Title | Priority | Blocks | Effort | Source | +|---|-------|----------|--------|--------|--------| +| NEW-1 | Tile collision system — walkability map + movement validation | Critical | #83, #101 | S | Tyre R1 §3.2 | +| NEW-2 | Tile-based A* pathfinding system (`pathfinding` crate) | High | #101 | M | Tyre R1 §3.1, Gestalt, Hoshe | +| NEW-3 | NPC path following and per-tick movement system | High | #101 | M | Tyre R1 §3.1 | +| NEW-4 | Interaction dispatcher — routes Interact input to subsystems | High | #168 (dialogue) | M | Tyre R1 §3.11.1, Gestalt | +| PROMOTE | #25 (Time system) → HIGH, rename to "Game clock and day-phase system" | High | #88 | M | Tyre R1 §3.4, Gestalt, Ozzie | +| PROMOTE | #201 (Deterministic replay) → CRITICAL | Critical | #211, #197 | L | Hoshe R1 §4 | + +### Testability Infrastructure Tickets + +| # | Title | Priority | Blocks | Effort | Source | +|---|-------|----------|--------|--------|--------| +| NEW-5 | Test runner bash scripts (test/run-rust, run-godot, run-ipc-*, run-all) | High | #215, #216 | S | Tyre R1 §4.6, Hoshe R1 §1 | +| NEW-6 | IPC serialization fixture files (Layer 1 test data) | High | #210 | S | Hoshe R1 §4 | +| NEW-7 | Information boundary negative test suite | High | #199 | M | Hoshe R1 §8 | +| NEW-8 | CauseChain component — information provenance tracking | High | #199, #119 | S | Hoshe R1 §7, Gestalt, Paula, Ozzie, Gore | +| NEW-9 | Playtest protocol definition — structured form for D-027 criteria | Medium | #195 | XS | Hoshe R1 §7 | + +### Soft Blocker Tickets (v0.1 feels broken without these) + +| # | Title | Priority | Blocks | Effort | Source | +|---|-------|----------|--------|--------|--------| +| NEW-10 | Client audio manager and spatial playback | High | #124, #125 | S | Tyre R1 §3.5 | +| NEW-11 | Define placeholder art specification (tile size, sprite dims, colors) | High | #133 | XS | Tyre R1 §3.6 | +| NEW-12 | Save state data model and serialization (shares design with #96) | High | shared with #96 | L | Tyre R1 §3.7 | +| NEW-13 | Save/load game flow — client integration | Medium | — | M | Tyre R1 §3.7 | +| NEW-14 | Game session management — start/save/resume flow | Medium | — | S | Tyre R1 §3.8 | +| NEW-15 | Time display on insert HUD | Medium | — | S | Tyre R1 §3.4 | +| NEW-16 | Knowledge/journal display — client (info inventory UI) | Medium | — | M | Tyre R1 §3.11.3 | + +### Tickets from Design Team Convergence (not mine to spec, but endorsing) + +These emerged from design team Round 1 analysis. I'm noting them because they have technical architecture implications, but the design agents should own the specifications: + +| Title | Proposed by | Technical note | +|-------|-------------|----------------| +| Opening hook / first 5 minutes experience design | Gestalt, Ozzie | Content + monologue trigger design, not a systems ticket | +| Observation event pipeline (perception → interpretation → monologue) | Gestalt, Ozzie | Integration glue — may be covered by CauseChain + monologue event wiring | +| Routine deviation detection system | Ozzie | Server-side system: compare NPC position vs expected routine position → generate monologue event. THIS is the core detective mechanic. | +| NPC-to-NPC conversation system | Gestalt | Server-side behavior system with sound events. Important for eavesdropping mechanic. | +| Follow mechanic — track NPC movement with distance/detection | Gestalt | Server-side input action + distance tracking. Required by D-027 criterion 4. | +| Triangle escalation events — observable NPC confrontations | Gestalt, Ozzie, Paula | Depends on #103 (relationship dynamics) and #105 (tolerance thresholds) — both need promotion to HIGH | +| Monologue content pack — separate authoring deliverable | Gestalt | Content volume estimation, not technical architecture | +| Contamination activation mechanic (simplified storyteller) | Gestalt, Ozzie | Even a timer-based trigger needs a system. Promote #162 to at minimum MEDIUM. | + +### Priority Promotions Endorsed (from design team analysis) + +Multiple design agents independently recommended these promotions. I'm endorsing from the technical side because they affect testing priority and system integration: + +| Ticket | Current | Recommended | Why (technical) | +|--------|---------|-------------|-----------------| +| #103 Relationship dynamics | Medium | **High** | Required for triangle activation tests, NPC-alive-off-screen tests | +| #105 Tolerance threshold triggers | Medium | **High** | The only trigger mechanism for triangle escalation — untestable without it | +| #171 Trust-gated gossip | Medium | **High** | Layer 3 dialogue is where information-boundary testing gets interesting | +| #172 Unprompted disclosure | Medium | **High** | NPCs volunteering info is a testable integration point (mood + trust + topic) | +| #162 Storyteller module activation | Low | **Medium** | Even a timer trigger needs a system — without it, no 30-min arc, no contamination | +| #178 Seed-based variation | Low | **High** | Nigel's argument is compelling: without this, replay ceiling = 2 playthroughs | + +### Ticket count summary + +| Category | Count | +|----------|-------| +| New hard blocker tickets | 4 (+ 2 promotions) | +| New testability tickets | 5 | +| New soft blocker tickets | 7 | +| Design team tickets (endorsed, not mine) | ~8 | +| Priority promotions endorsed | 6 | +| **Total new tickets from Tyre** | **16** | + +**S = Small (1-3 days), M = Medium (3-5 days), L = Large (5-10 days), XS = Extra Small (< 1 day)** + +--- + +## Cross-Agent Alignment Summary + +### Where Hoshe and I now fully agree + +| Topic | Status | +|-------|--------| +| Rust test organization: hybrid | Agreed from Round 1 | +| IPC testing: three-layer architecture | Merged — Hoshe's layers extend my "real IPC" position | +| Godot framework: gdUnit4 | I changed my recommendation after reading Hoshe's comparison | +| Bash wrapper scripts | Agreed from Round 1 | +| No test pollution in production code | Agreed from Round 1 | +| CauseChain as production component | Hoshe proposed, I endorse | +| cargo-nextest for Rust | Agreed from Round 1 | +| #201 promotion to CRITICAL | Hoshe proposed, I endorse | +| Flaky tests are bugs | Agreed from Round 1 | +| JSON as agent output format | Agreed from Round 1 | + +### Where I extend Hoshe's proposals + +- **Test priority ordering** aligned with design team's hard blocker findings (section 4) +- **Monologue pipeline test** as highest-value integration test (section 4) +- **Test fixture files** with pre-generated maps and NPC configs (section 3) + +### Where the design team changes my thinking + +- **The monologue system is the critical integration point**, not just perception or IPC. Tests should exercise the monologue pipeline early and often. +- **Routine deviation detection** is a system I hadn't called out in Round 1 — it needs a ticket AND it needs tests from day one. +- **The opening hook** is a content concern, but it affects WHEN we need content validation tests running. + +--- + +*That's my Round 2 synthesis. Hoshe and I are aligned on all testability decisions. The GUT/gdUnit4 disagreement is resolved in Hoshe's favor. The three-layer IPC architecture is stronger than either of our individual proposals. The design team's findings add content-integration testing as a priority I hadn't fully weighted in Round 1.* + +*The testability decisions are ready for team confirmation. The new tickets are ready for Si to process.* + +*— TYRE* diff --git a/docs/workshops/v01-gap-analysis/si-ticket-changes.md b/docs/workshops/v01-gap-analysis/si-ticket-changes.md new file mode 100644 index 000000000..f21e89d3f --- /dev/null +++ b/docs/workshops/v01-gap-analysis/si-ticket-changes.md @@ -0,0 +1,249 @@ +# v0.1 Gap Analysis Workshop — Ticket Changes + +**Processed by:** Si (Project Manager) +**Date:** 2026-02-11 +**Source:** Round 2 workshop outputs (Gestalt, Tyre, Ozzie, Paula, Nigel, Gore) +**Ticket count before:** 232 | **After:** 273 (+41) + +--- + +## Summary + +The v0.1 gap analysis workshop identified significant gaps in the ticket catalog: missing infrastructure (collision, pathfinding, time system), a missing experience layer (observation pipeline, interaction verbs), and underpriced tickets across social, dialogue, and replayability systems. + +**Changes made:** +- 15 priority promotions on existing tickets +- 3 new epics created +- 38 new stories created +- 21 dependency records added +- 1 existing ticket renamed and reparented (#25) + +--- + +## 1. Priority Promotions (15 tickets) + +### MEDIUM → HIGH (11 tickets) + +| ID | Title | Old | New | Agents Recommending | Rationale | +|----|-------|-----|-----|--------------------|-----------| +| #103 | Relationship dynamics | medium | **high** | Gestalt, Paula, Ozzie | Required for triangle activation, NPC attachment, social propagation | +| #105 | Tolerance threshold triggers | medium | **high** | Gestalt, Paula, Ozzie | Only triangle activation mechanism; without it, triangles are backstory | +| #171 | Trust-gated gossip (Layer 3) | medium | **high** | Ozzie, Paula | Where daily life becomes interesting; 30-min sustainer | +| #172 | Unprompted disclosure (Layer 4) | medium | **high** | Ozzie, Paula, Gestalt | NPC-initiated story moments; off-screen event narration | +| #173 | Trait modifier system | medium | **high** | Paula | Required for seed-variation narrative depth; makes each seed's NPCs distinct | +| #175 | Entanglement ratio configuration | medium | **high** | Nigel | D-029 anti-metagaming requires implementation | +| #176 | NPC pool generation | medium | **high** | Nigel | Per-seed NPC assignment foundational for variation | +| #121 | Character voice variation | medium | **high** | Ozzie, Gore, Paula | Must be interpretive framing, not just tonal; thesis-proving system | +| #126 | Medium-range visual indicators | medium | **high** | Ozzie, Gestalt | Fog-edge tension — hearing things you can't see | + +### LOW → HIGH (2 tickets) + +| ID | Title | Old | New | Agents Recommending | Rationale | +|----|-------|-----|-----|--------------------|-----------| +| #162 | Storyteller module activation | low | **high** | Ozzie, Gestalt, Gore | Without it, no arc; 30-min runway has no endpoint | +| #178 | Seed-based variation | low | **high** | Nigel (emphatic), all | Replay ceiling = 2 without it; the replayability engine | + +### HIGH → CRITICAL (3 tickets) + +| ID | Title | Old | New | Agents Recommending | Rationale | +|----|-------|-----|-----|--------------------|-----------| +| #201 | Deterministic replay system | high | **critical** | Hoshe, Tyre | Core architectural principle (D-010); blocks sync tests (#211), divergence tests (#197) | +| #182 | Divergent starting knowledge | high | **critical** | Nigel | Core character differentiator; Gore's "different realities" starts here | +| #183 | Divergent relationships | high | **critical** | Nigel | Inverted emotional landscape per character; non-negotiable for two-reality proof | + +### Renamed + Promoted (1 ticket) + +| ID | Old Title | New Title | Old Priority | New Priority | Notes | +|----|-----------|-----------|-------------|-------------|-------| +| #25 | Time system | **Game clock and day-phase system** | medium | **high** | Resolves Q-009. Reparented under new epic #233. 10 tps, 4 day phases, diegetic clock display. | + +--- + +## 2. New Epics (3) + +| ID | Title | Parent | Priority | Description | +|----|-------|--------|----------|-------------| +| #233 | **Movement & Collision** | #29 Core Simulation | critical | Tile collision, pathfinding, NPC movement. Hard blockers — nothing spatial works without these. | +| #234 | **Observation & Interaction** | #30 Rendering & Perception | critical | Unified observation pipeline and player interaction. The experience layer connecting perception to gameplay. | +| #235 | **Game State Management** | #28 Engine Architecture | high | Save/load and session management for playable v0.1 sessions. | + +--- + +## 3. New Stories (38) + +### CRITICAL (3 stories) + +| ID | Title | Epic | Source | +|----|-------|------|--------| +| #236 | Tile collision system | #233 Movement & Collision | Tyre R1, Gestalt R2 (C-1) | +| #239 | Observation event generator | #234 Observation & Interaction | Ozzie, Paula, Gestalt merged (C-4) | +| #240 | Player interaction system and dispatcher | #234 Observation & Interaction | Gestalt, Tyre merged (C-5) | + +### HIGH (24 stories) + +| ID | Title | Epic | Source | +|----|-------|------|--------| +| #237 | Tile-based A* pathfinding | #233 Movement & Collision | Tyre R1, Gestalt R2 (C-2a) | +| #238 | NPC path following and movement | #233 Movement & Collision | Tyre R1 (C-2b) | +| #241 | Follow mechanic | #234 Observation & Interaction | Gestalt R2 (H-1) | +| #242 | Examine mechanic | #234 Observation & Interaction | Gestalt R2 (H-2) | +| #243 | Routine deviation detection | #234 Observation & Interaction | Ozzie R1+R2, Paula R1 | +| #244 | NPC player-awareness behavior | #234 Observation & Interaction | Gestalt R2 (H-5) | +| #247 | NPC-to-NPC conversation system | #41 NPC Behavior | Gestalt R2 (H-4) | +| #248 | Character goal/pressure framework | #41 NPC Behavior | Gestalt R2, Paula R2 (H-8) | +| #249 | Player-action social propagation | #41 NPC Behavior | Paula R1+R2, Nigel R2 (H-6) | +| #250 | Triangle escalation system | #42 Triangle Generation | Gestalt, Paula, Ozzie (H-3) | +| #251 | Tell visual/behavioral expression | #47 Top-down Renderer | Paula R1+R2, Ozzie R2 (H-7) | +| #252 | Placeholder art specification | #47 Top-down Renderer | Tyre R1 (H-13) | +| #253 | Monologue content architecture | #45 Internal Monologue | Gestalt, Paula, Gore (H-10) | +| #254 | Contamination activation mechanic | #53 Three-Tier Content | Gestalt R2 (H-11) | +| #255 | Client audio manager | #46 Sound Propagation | Tyre R1 (H-12) | +| #256 | Save state data model | #235 Game State Management | Tyre R1 (H-14) | +| #259 | First 5 minutes experience design | #59 Vertical Slice Authoring | Gestalt R2, Ozzie R1+R2 (H-9) | +| #260 | Opening hook content per character | #59 Vertical Slice Authoring | Gestalt R2, Ozzie R2, Nigel R2 | +| #261 | Dual Lens Authoring Guide | #59 Vertical Slice Authoring | Gore R2, Paula R2, Ozzie R2 | +| #269 | CauseChain component | #49 Information Boundary | Hoshe R1, Tyre R2 (T-2) | +| #270 | Test runner bash scripts | #61 Rust Test Infra | Tyre R1+R2 | +| #271 | IPC serialization fixture files | #61 Rust Test Infra | Hoshe R1, Tyre R2 | +| #272 | Information boundary negative test suite | #63 Integration Test Framework | Hoshe R1, Tyre R2 (T-1) | + +### MEDIUM (10 stories) + +| ID | Title | Epic | Source | +|----|-------|------|--------| +| #245 | Wait/time-skip mechanic | #234 Observation & Interaction | Gestalt R2 (M-1) | +| #246 | Basic environmental interaction | #234 Observation & Interaction | Gestalt R2 (M-2) | +| #257 | Save/load game flow | #235 Game State Management | Tyre R1 (M-5) | +| #258 | Game session management | #235 Game State Management | Tyre R1 (M-6) | +| #262 | Environmental text content | #59 Vertical Slice Authoring | Gestalt R2 (M-3) | +| #263 | Time display on insert HUD | #51 Diegetic Insert/Minimap | Tyre R1 (M-7) | +| #264 | Knowledge/journal display | #51 Diegetic Insert/Minimap | Tyre R1 (M-4) | +| #265 | Demo scenario specification | #60 Success Criteria | Ozzie R1+R2 (M-8) | +| #266 | Same-character-different-seed validation | #60 Success Criteria | Nigel R2 (M-10) | +| #267 | Playtest protocol definition | #60 Success Criteria | Hoshe R1 (M-11) | + +### LOW (1 story) + +| ID | Title | Epic | Source | +|----|-------|------|--------| +| #273 | Test output formatter CLI | #64 Testability Arch Refinement | Hoshe R1 (T-3) | + +### MEDIUM (population — 1 more) + +| ID | Title | Epic | Source | +|----|-------|------|--------| +| #268 | False positive NPC design | #56 Population Management | Nigel R1+R2 (M-9) | + +--- + +## 4. Dependencies Added (21 records) + +### Critical Path: Movement Foundation + +``` +#236 Tile collision ──blocks──→ #237 A* pathfinding ──blocks──→ #238 NPC path following ──blocks──→ #101 Routine execution +#236 Tile collision ──blocks──→ #83 Moving character proof +#25 Game clock ──blocks──→ #88 Daily routine system +``` + +### Critical Path: Observation Pipeline + +``` +#239 Observation event generator ──blocks──→ #119 Monologue event generation +#240 Interaction dispatcher ──blocks──→ #168 Tagged line pool structure (dialogue) +#240 Interaction dispatcher ──blocks──→ #241 Follow mechanic +#240 Interaction dispatcher ──blocks──→ #242 Examine mechanic +#88 Daily routine system ──blocks──→ #243 Routine deviation detection +``` + +### Critical Path: Triangle Activation + +``` +#103 Relationship dynamics ──blocks──→ #250 Triangle escalation system +#105 Tolerance threshold triggers ──blocks──→ #250 Triangle escalation system +``` + +### Content Pipeline + +``` +#261 Dual Lens Authoring Guide ──blocks──→ #190 Workplace content pack +#261 Dual Lens Authoring Guide ──blocks──→ #191 Bar content pack +#261 Dual Lens Authoring Guide ──blocks──→ #192 Smuggling ring content pack +#259 First 5 min experience ──blocks──→ #260 Opening hook content +``` + +### Infrastructure + +``` +#252 Placeholder art spec ──blocks──→ #133 Placeholder art pipeline +#255 Client audio manager ──blocks──→ #124 Sound event system +#255 Client audio manager ──blocks──→ #125 Close-range stereo audio +#269 CauseChain component ──blocks──→ #199 Criterion 4: Emergent observation +#256 Save state data model ──blocks──→ #257 Save/load game flow +``` + +--- + +## 5. Updated Ticket Catalog Summary + +| Priority | Final Count | +|----------|-------------| +| Critical | 83 | +| High | 117 | +| Medium | 58 | +| Low | 15 | +| **Total** | **273** | + +**Changes:** +41 new tickets (3 epics, 38 stories). 15 existing tickets promoted. 21 new dependency records (65 total). + +--- + +## 6. Critical Path for v0.1 + +The workshop revealed a clear dependency chain that must be sequenced: + +**Sprint 1: Foundation (make it run)** +- #236 Tile collision (critical) → #237 Pathfinding (high) → #238 NPC movement (high) +- #25 Game clock (high) → unblocks #88 Daily routines +- #65-68 Rust server setup (critical, existing) +- #70-73 Godot client setup (critical, existing) +- #75-79 IPC bridge (critical, existing) + +**Sprint 2: Integration (make it work)** +- #81-83 Client-server integration (critical, existing) +- #239 Observation event generator (critical) +- #240 Player interaction dispatcher (critical) +- #86-89 NPC data model (critical-high, existing) +- #110-113 Fog of perception (critical, existing) + +**Sprint 3: Experience (make it feel)** +- #241-244 Observation verbs and deviation detection (high) +- #247-250 NPC conversation, goals, propagation, triangle escalation (high) +- #119-122 Internal monologue + #253 content architecture (high) +- #253 Monologue content architecture (high) +- #269 CauseChain component (high) + +**Sprint 4: Content (make it mean something)** +- #261 Dual Lens Authoring Guide (high) → blocks all content packs +- #259-260 First 5 minutes + opening hooks (high) +- #190-192 Content packs (critical, existing) +- #251 Tell visual/behavioral expression (high) + +**Sprint 5: Validation (prove it works)** +- #195-199 Success criteria validation (high, existing) +- #265 Demo scenario (medium) +- #266 Seed validation test (medium) +- #267 Playtest protocol (medium) + +--- + +## 7. Decisions Confirmed by Workshop + +The following decisions should be recorded (pending team lead confirmation): + +1. **Godot test framework = gdUnit4** (Tyre reversed GUT recommendation after Hoshe's analysis) +2. **IPC testing = three-layer architecture** (fixture, protocol mock, real integration) +3. **CauseChain is a production component**, not test pollution +4. **Time system: 10 tps, 4 day phases, diegetic clock** (resolves Q-009) +5. **Deterministic replay is architectural requirement**, not just test infrastructure +6. **Dual Lens Authoring Guide must precede content authoring** diff --git a/docs/workshops/v01-gap-analysis/v01-gap-analysis-workshop-brief.md b/docs/workshops/v01-gap-analysis/v01-gap-analysis-workshop-brief.md new file mode 100644 index 000000000..17513f5ed --- /dev/null +++ b/docs/workshops/v01-gap-analysis/v01-gap-analysis-workshop-brief.md @@ -0,0 +1,484 @@ +# v0.1 GAP Analysis Workshop Brief + +**Goal:** Stress-test the full v0.1 plan against concept proof, fun delivery, and completeness +**Participants:** Jeroen (lead), full team as needed +**Ticket scope:** 232 tickets across 7 initiatives +**v0.1 target:** D-027 vertical slice — smuggler + detective, 30-min playable, fundamentally different playthroughs + +## Workshop Tracks + +### Track 1: Strength of Concept Proof + +The vertical slice must prove these claims about The Settled Reach: + +| Claim | How the v0.1 proves it | Which tickets deliver it | Risk | +|-------|----------------------|------------------------|------| +| **Asymmetric information is the core mechanic** | Smuggler and detective see the same world differently | #138-142 (info boundaries), #182-183 (divergent knowledge/relationships) | ? | +| **Fog of perception creates tension** | Player doesn't know what they can't see | #110-113 (shadowcasting → fog rendering) | ? | +| **NPCs feel alive without player attention** | Routines continue, relationships shift off-screen | #88 (daily routines), #93-99 (simulation tiers), #101 (routine execution) | ? | +| **Observation is a mechanic, not a cutscene** | Player deduces from watching, overhearing, noticing | #115 (NPC vision), #124-128 (sound model), #119-122 (internal monologue) | ? | +| **Same world, different story** | Two playthroughs are mechanically distinct, not just narratively | #179-183 (character builds), #196-199 (success criteria) | ? | +| **Social triangles create emergent drama** | NPC relationships produce situations the designers didn't script | #106-109 (triangle generation), #175-176 (entanglement ratio) | ? | + +**Questions for the team:** +- Does the ticket catalog actually deliver on each claim, or are there gaps? +- Which claims are weakest in the current plan? +- What's the minimum bar for each claim at v0.1? (We don't need perfection, but we need proof.) +- Are there claims the game should be making that aren't listed here? + +### Track 2: Fun & Wow Factor + +A concept proof that isn't fun to play is a failed concept proof. Evaluate the plan against player experience: + +**First 5 minutes:** +- What does the player see when they start? (Ticket coverage?) +- Is there an immediate hook — a reason to keep playing? +- Does the UI communicate the asymmetric information concept without a tutorial? + +**The "aha" moment:** +- When does the player first realize they're seeing a different world than the other character would? +- When do they first catch an NPC doing something suspicious through observation? +- When does the internal monologue first surprise them? +- Are these moments in the ticket plan, or are we hoping they emerge? + +**The 30-minute arc:** +- What's the shape of a play session? Is there rising tension, discovery, payoff? +- The D-027 success criteria say "30-min daily life runway" — is daily life interesting enough to sustain 30 minutes without a scripted event? +- Where does the storyteller kick in? (ticket #162 is low priority — is that right?) + +**Missing wow moments:** +- Sound: Three-range model (#124-128) is specced — but is there a moment where the player hears something through a wall and has to decide whether to investigate? +- Internal monologue: Is there a moment where the character's thoughts contradict what the player sees? +- NPCs: Is there a moment where an NPC the player trusted turns out to be lying? + +**Questions for the team (especially Ozzie, Gestalt):** +- What's the single most exciting thing that can happen in the first 30 minutes? +- Are we front-loading the fun, or does the player need to grind through systems before experiencing the core loop? +- Which tickets contribute to wow, and which are pure infrastructure? +- Is there a "demo moment" — something we could show someone in 2 minutes to sell the concept? + +### Track 3: Things We May Have Forgotten + +Systematic check for gaps in the 232-ticket plan: + +**Player agency:** +- Player can move, look, listen — but what can they DO? +- Is there an interaction system? (Talk to NPC, examine object, pick up item, use door) +- Are action verbs captured in tickets? I see dialogue (#168-174) but not physical interaction +- Where's the player's inventory/journal/notes system? + +**Game state:** +- Save/load system — not captured anywhere? +- Session management — how does a 30-min play session start and end? +- Game over / failure states — what happens when things go wrong? + +**Feedback loops:** +- How does the player know their actions had consequences? +- How does the player know they missed something? +- Is there a reputation/standing feedback mechanism beyond the NPC relationship system? + +**Content volume:** +- 20-30 NPCs with 10-axis data models, daily routines, relationship triangles — is this achievable for v0.1? +- Three social sites with full content packs — what's the actual writing volume for Mellanie? +- Are placeholder/stub levels defined for systems that are specced but too deep for v0.1? + +**Technical gaps:** +- Pathfinding — NPCs need to navigate the station district, but there's no pathfinding ticket +- Collision — player and NPC movement needs collision detection +- Z-levels — #114 is low priority, but does the station district have multiple levels? +- Time system — Q-009 is open, but daily routines (#88) depend on it +- Audio engine — sound propagation is specced (#124-128) but is there a basic audio playback system? +- Asset pipeline — #133 covers placeholder art, but what format? What resolution? What's the sprite spec? + +**Process gaps:** +- No definition of "done" for v0.1 beyond D-027's four success criteria +- No playtest protocol — who tests, how, what feedback is captured? +- No art direction decision (Q-003 still open) — affects every visual ticket + +### Track 4: Testability Deep-Dive + +**Ticket #214 — Refinement discussion (critical, blocks #215-217)** + +``` +#34 [initiative] Testability Infrastructure (high) +│ +├── #64 [epic] Testability Architecture Refinement (critical) +│ ├── #214 [story] Refinement discussion - Multi-agent (critical) ← NEEDS WORKSHOP +│ ├── #215 [story] Testing pattern documentation (high) — blocked by #214 +│ ├── #216 [story] Tooling requirements spec (high) — blocked by #214 +│ └── #217 [story] Production code constraints (high) — blocked by #214 +│ +├── #61 [epic] Rust/bevy_ecs Test Infrastructure (high) +│ ├── #200 [story] Test module organization (high) +│ ├── #201 [story] Deterministic replay system (high) +│ ├── #202 [story] ECS state inspection (high) +│ ├── #203 [story] Behavior validation framework (medium) +│ └── #204 [story] Performance benchmarks (medium) +│ +├── #62 [epic] Godot Client Test Infrastructure (high) +│ ├── #205 [story] GDScript test framework setup (high) +│ ├── #206 [story] Scene testing utilities (high) +│ ├── #207 [story] Input simulation (medium) +│ ├── #208 [story] Rendering verification (medium) +│ └── #209 [story] UI validation framework (medium) +│ +└── #63 [epic] Integration Test Framework (medium) + ├── #210 [story] IPC protocol tests (high) + ├── #211 [story] Sync verification tests (high) + ├── #212 [story] Full playthrough automation (medium) + └── #213 [story] Performance profiling (low) +``` + +**Core design constraint:** Test harness attaches externally as modules. Minimal production code pollution. + +**Key questions (Tyre, Hoshe, Troblum):** +- Rust: External test crate vs `#[cfg(test)]` vs hybrid? +- Godot: GUT vs gdUnit4? Can Claude Code run `godot --headless`? +- Integration: Mock subprocess or real IPC for tests? +- What test output format works best for agent consumption? +- Where's the line between acceptable seam and test pollution? +- Test runners as simple bash commands (like `db/connectors/sqlite-*`)? + +--- + +## Full v0.1 Ticket Catalog + +All 232 tickets organized by initiative. Reference for all workshop tracks. + +### Initiative: Engine Architecture — Godot + Rust IPC (#28, critical, D-020) + +| ID | Type | Title | Priority | +|----|------|-------|----------| +| **35** | epic | Rust Simulation Server Foundation | critical | +| 65 | story | Project structure setup | critical | +| 66 | story | ECS world initialization | critical | +| 67 | story | Deterministic tick system | critical | +| 68 | story | Basic entity components | critical | +| 69 | story | Standalone CLI test harness | high | +| 218 | task | Create simulation/ directory structure | critical | +| 219 | task | Initialize Cargo workspace | critical | +| 220 | task | Configure project metadata | critical | +| 221 | task | Create main.rs entry point | critical | +| 222 | task | Set up CI placeholder | low | +| **36** | epic | Godot Client Foundation | critical | +| 70 | story | Godot project initialization | critical | +| 71 | story | Tilemap rendering system | critical | +| 72 | story | Entity sprite system | critical | +| 73 | story | Input capture system | critical | +| 74 | story | Basic UI framework | high | +| 223 | task | Create client/ directory structure | critical | +| 224 | task | Initialize Godot 4 project | critical | +| 225 | task | Create main scene hierarchy | critical | +| 226 | task | Configure camera settings | critical | +| 227 | task | Set up project settings | high | +| **37** | epic | IPC Bridge & Protocol | critical | +| 75 | story | Protocol message definitions | critical | +| 76 | story | MessagePack serialization - Rust | critical | +| 77 | story | MessagePack serialization - GDScript | critical | +| 78 | story | LocalBridge implementation - Rust | critical | +| 79 | story | LocalBridge implementation - GDScript | critical | +| 80 | story | NetworkBridge stub | low | +| 228 | task | Create protocol/ directory | critical | +| 229 | task | Define ObserverSnapshot structure | critical | +| 230 | task | Define PlayerInput structure | critical | +| 231 | task | Define entity data structures | critical | +| 232 | task | Create protocol versioning scheme | high | +| **38** | epic | Client-Server Integration | critical | +| 81 | story | End-to-end connection test | critical | +| 82 | story | Tick loop synchronization | critical | +| 83 | story | Moving character proof | critical | +| 84 | story | Multiple entity sync | high | +| 85 | story | Error handling & recovery | high | + +### Initiative: Core Simulation — NPCs & Tiers (#29, critical, D-024/D-026) + +| ID | Type | Title | Priority | +|----|------|-------|----------| +| **39** | epic | NPC Data Model | critical | +| 86 | story | Core NPC components | critical | +| 87 | story | Relationship system | critical | +| 88 | story | Daily routine system | critical | +| 89 | story | Information inventory | high | +| 90 | story | Personality & tell system | high | +| 91 | story | Skill system & combat flag | medium | +| 92 | story | NPC generation pipeline | high | +| **40** | epic | Simulation Tier System | critical | +| 93 | story | Tier marker components | critical | +| 94 | story | Active tier simulation | critical | +| 95 | story | Background tier state machines | high | +| 96 | story | State serialization system | high | +| 97 | story | Timestamp-based eviction | high | +| 98 | story | Scope tag system | high | +| 99 | story | Tier transition logic | high | +| 100 | story | Ungenerated to instantiation | medium | +| **41** | epic | NPC Behavior Systems | high | +| 101 | story | Routine execution system | high | +| 102 | story | Mood system | medium | +| 103 | story | Relationship dynamics | medium | +| 104 | story | Job performance simulation | low | +| 105 | story | Tolerance threshold triggers | medium | +| **42** | epic | Triangle Generation | high | +| 106 | story | Triangle definition schema | high | +| 107 | story | Intra-template triangle generation | high | +| 108 | story | Cross-template triangle generation | medium | +| 109 | story | Triangle validation | medium | + +### Initiative: Rendering & Perception System (#30, critical, D-011/D-015/D-016/D-017/D-018/D-019) + +| ID | Type | Title | Priority | +|----|------|-------|----------| +| **43** | epic | Fog of Perception - Vision System | critical | +| 110 | story | Shadowcasting algorithm - server | critical | +| 111 | story | Vision cone implementation | critical | +| 112 | story | Observer visibility query | critical | +| 113 | story | Fog rendering - client | critical | +| 114 | story | Multi-z-level LOS | low | +| 115 | story | NPC vision system | high | +| **44** | epic | Camera System | critical | +| 116 | story | Camera lock to character | critical | +| 117 | story | Smooth camera movement | high | +| 118 | story | Camera rotation stub | low | +| **45** | epic | Internal Monologue System | high | +| 119 | story | Monologue event generation - server | high | +| 120 | story | Monologue line pool system | high | +| 121 | story | Character voice variation | medium | +| 122 | story | Monologue display - client | high | +| 123 | story | Unreliable narrator mechanics | low | +| **46** | epic | Sound Propagation Model | high | +| 124 | story | Sound event system - server | high | +| 125 | story | Close-range stereo audio - client | high | +| 126 | story | Medium-range visual indicators | medium | +| 127 | story | Long-range insert notifications | low | +| 128 | story | Sound propagation physics | low | +| **47** | epic | Top-down Renderer | critical | +| 129 | story | Tile rendering engine | critical | +| 130 | story | Entity sprite management | critical | +| 131 | story | Fog overlay rendering | critical | +| 132 | story | Lighting system | medium | +| 133 | story | Placeholder art pipeline | high | +| **48** | epic | Perception Mode Framework | medium | +| 134 | story | Observer query abstraction | medium | +| 135 | story | Natural vision mode | high | +| 136 | story | Perception mode selector - client | low | +| 137 | story | Additional mode stubs | low | + +### Initiative: Map & Navigation (#31, high, D-010/D-012/D-013/D-014) + +| ID | Type | Title | Priority | +|----|------|-------|----------| +| **49** | epic | Information Boundary System | critical | +| 138 | story | Information tag schema | critical | +| 139 | story | Component-level access control | critical | +| 140 | story | Entity visibility filtering | critical | +| 141 | story | Knowledge-based information gating | high | +| 142 | story | NPC information boundaries | high | +| **50** | epic | Chunk-based Map System | high | +| 143 | story | Chunk data structure | high | +| 144 | story | Chunk generation system | high | +| 145 | story | Chunk loading/unloading | high | +| 146 | story | Chunk serialization | medium | +| 147 | story | Borderless expansion stub | low | +| **51** | epic | Diegetic Insert/Minimap | high | +| 148 | story | POI data model | high | +| 149 | story | POI discovery system | high | +| 150 | story | Character-specific POI filtering | medium | +| 151 | story | Minimap rendering - client | high | +| 152 | story | POI manipulation mechanics | low | +| **52** | epic | Station District Map - v0.1 Revision | high | +| 153 | story | Station district layout design | critical | +| 154 | story | Functional cluster spatial specs | high | +| 155 | story | Hand-crafted location authoring | high | +| 156 | story | Procedural district filler | medium | +| 157 | story | Gate corridor template | high | + +### Initiative: Content Architecture (#32, high, D-023/D-025/D-028/D-029) + +| ID | Type | Title | Priority | +|----|------|-------|----------| +| **53** | epic | Three-Tier Content Pipeline | high | +| 158 | story | Tier 1 drama module schema | medium | +| 159 | story | Tier 2 template definition format | high | +| 160 | story | Tier 3 procedural generator | medium | +| 161 | story | Template instantiation engine | high | +| 162 | story | Storyteller module activation | low | +| **54** | epic | Social Site Template System | high | +| 163 | story | Role definition schema | high | +| 164 | story | Spatial requirement specification | high | +| 165 | story | Single-ownership model | high | +| 166 | story | Template-to-instance mapping | high | +| 167 | story | Cross-template reference system | medium | +| **55** | epic | Dialogue System Architecture | high | +| 168 | story | Tagged line pool structure | high | +| 169 | story | Layer 1: Access tier filtering | high | +| 170 | story | Layer 2: Relationship history | high | +| 171 | story | Layer 3: Trust-gated gossip | medium | +| 172 | story | Layer 4: Unprompted disclosure | medium | +| 173 | story | Trait modifier system | medium | +| 174 | story | Dialogue UI - client | high | +| **56** | epic | Population Management | medium | +| 175 | story | Entanglement ratio configuration | medium | +| 176 | story | NPC pool generation | medium | +| 177 | story | Module attachment logic | low | +| 178 | story | Seed-based variation | low | + +### Initiative: Vertical Slice Content (#33, critical, D-027) + +| ID | Type | Title | Priority | +|----|------|-------|----------| +| **57** | epic | Playable Characters - Smuggler & Detective | critical | +| 179 | story | Character definition schema | critical | +| 180 | story | Smuggler character build | critical | +| 181 | story | Detective character build | critical | +| 182 | story | Divergent starting knowledge | high | +| 183 | story | Divergent relationships | high | +| **58** | epic | Station District Content | critical | +| 184 | story | Workplace template - logistics hub | critical | +| 185 | story | Social venue template - bar | critical | +| 186 | story | Smuggling ring template | critical | +| 187 | story | Shared NPC coordination | high | +| 188 | story | Triangle instantiation | high | +| **59** | epic | Vertical Slice Authoring | high | +| 189 | story | Cultural generation guide - Miri | critical | +| 190 | story | Workplace content pack - Mellanie | critical | +| 191 | story | Bar content pack - Mellanie | critical | +| 192 | story | Smuggling ring content pack - Mellanie | critical | +| 193 | story | Line previewer CLI - Tyre | critical | +| 194 | story | Generation pass expansion | high | +| **60** | epic | Success Criteria Validation | high | +| 195 | story | Test plan creation - Hoshe | high | +| 196 | story | Criterion 1: 30-min daily life runway | high | +| 197 | story | Criterion 2: Fundamentally different playthroughs | high | +| 198 | story | Criterion 3: Emotional NPC attachment | high | +| 199 | story | Criterion 4: Emergent observation mechanics | high | + +### Initiative: Testability Infrastructure (#34, high) + +| ID | Type | Title | Priority | +|----|------|-------|----------| +| **64** | epic | Testability Architecture Refinement | critical | +| 214 | story | Refinement discussion - Multi-agent | critical | +| 215 | story | Testing pattern documentation | high | +| 216 | story | Tooling requirements spec | high | +| 217 | story | Production code constraints | high | +| **61** | epic | Rust/bevy_ecs Test Infrastructure | high | +| 200 | story | Test module organization | high | +| 201 | story | Deterministic replay system | high | +| 202 | story | ECS state inspection | high | +| 203 | story | Behavior validation framework | medium | +| 204 | story | Performance benchmarks | medium | +| **62** | epic | Godot Client Test Infrastructure | high | +| 205 | story | GDScript test framework setup | high | +| 206 | story | Scene testing utilities | high | +| 207 | story | Input simulation | medium | +| 208 | story | Rendering verification | medium | +| 209 | story | UI validation framework | medium | +| **63** | epic | Integration Test Framework | medium | +| 210 | story | IPC protocol tests | high | +| 211 | story | Sync verification tests | high | +| 212 | story | Full playthrough automation | medium | +| 213 | story | Performance profiling | low | + +### Legacy Seed Initiatives (D-001 through D-019) + +Auto-seeded from early decisions. Superseded by structured initiatives above. Retained for traceability. + +| ID | Title | Decision | +|----|-------|----------| +| 1 | Custom game, not a mod | D-001 | +| 2 | Commonwealth as first campaign | D-003 | +| 3 | Single character first-person story generator | D-005 | +| 4 | Prototype scenario — Institute/Armstrong City/Guardians | D-006 | +| 5 | Five pillars of game design | D-007 | +| 6 | Action pillar design principles | D-008 | +| 7 | Multiplayer — design for it, build single-player first | D-009 | +| 8 | Multiplayer-ready architectural baseline | D-010 | +| 9 | Fog of perception non-negotiable | D-011 | +| 10 | Chunk-based map architecture | D-012 | +| 11 | Diegetic insert/POI navigation | D-013 | +| 12 | v0.1 map specification | D-014 | +| 13 | Camera locked to character | D-015 | +| 14 | Internal monologue system | D-016 | +| 15 | Perception modes as character build | D-017 | +| 16 | Three-range sound model | D-018 | +| 17 | Top-down with 3D cutscenes | D-019 | + +### Open Questions (unparented stories) + +| ID | Title | Ref | Status | +|----|-------|-----|--------| +| 18 | Game engine selection | Q-001 | ready | +| 19 | v0.1 prototype scope | Q-002 | backlog | +| 20 | Art direction | Q-003 | backlog | +| 21 | One campaign or separate eras | Q-004 | backlog | +| 22 | Prototype scale | Q-005 | backlog | +| 23 | Target platforms | Q-007 | backlog | +| 24 | Licensing/distribution | Q-008 | backlog | +| 25 | Time system | Q-009 | backlog | +| 26 | Storyteller AI design | Q-010 | backlog | +| 27 | Character selection roster | Q-011 | backlog | + +--- + +## Dependency Map + +``` +Engine Foundation: + #65 Project structure → #66 ECS world init → #67 Deterministic tick → #68 Basic entity components + #35 Rust Server Foundation ──┐ + #36 Godot Client Foundation ─┤→ #38 Client-Server Integration + #37 IPC Bridge & Protocol ───┘ + +IPC Chain: + #75 Protocol messages ──┬→ #76 MsgPack Rust → #78 LocalBridge Rust ──┐ + └→ #77 MsgPack GDS → #79 LocalBridge GDS ──┤→ #81 E2E test → #82 Tick sync → #83 Moving char proof + +NPC Pipeline: + #39 NPC Data Model ──┬→ #40 Simulation Tiers + ├→ #41 NPC Behavior Systems + ├→ #42 Triangle Generation + └→ #54 Social Site Templates → #53 Three-Tier Pipeline + +Perception Chain: + #110 Shadowcasting → #111 Vision cone → #112 Observer query → #113 Fog rendering + #43 Fog of Perception → #47 Top-down Renderer + +NPC Components: + #86 Core NPC components → #92 NPC generation pipeline + #87 Relationship system → #101 Routine execution + #89 Information inventory → #90 Personality & tell system + +Content Pipeline: + #158 Tier 1 drama schema → #159 Tier 2 template format + #55 Dialogue System → #59 Vertical Slice Authoring + #189 Cultural guide (Miri) ──┬→ #190 Workplace pack (Mellanie) + #193 Line previewer (Tyre) ──┤→ #191 Bar pack (Mellanie) + └→ #192 Smuggling ring pack (Mellanie) + +Station District: + #153 Layout design ────────┐ + #185 Bar template ─────────┤ + #186 Smuggling template ───┤→ #188 Triangle instantiation + #187 Shared NPC coord ─────┘ + +Vertical Slice Validation: + #57 Playable Characters ─┐ + #58 Station Content ─────┤→ #60 Success Criteria Validation + #59 Authoring ───────────┘ + +Testability: + #214 Refinement discussion ──┬→ #215 Testing pattern docs + ├→ #216 Tooling requirements + └→ #217 Production code constraints +``` + +--- + +## Workshop Outputs Expected + +1. **Concept proof scorecard** — each claim rated for ticket coverage and risk +2. **Fun/wow gap list** — missing moments, front-loaded vs back-loaded experience concerns +3. **Missing ticket list** — new stories for forgotten systems (interaction, save/load, pathfinding, etc.) +4. **Priority adjustments** — tickets that should be promoted or demoted based on analysis +5. **Testability decisions** — Rust patterns, Godot framework, production code boundaries +6. **Open question resolutions** — which Q-items block v0.1 and need decisions now +7. **Updated dependency map** — new dependencies from discovered gaps