docs(workshops): add 5 architecture spike workshop briefs

Workshop briefs for the larger spikes identified by the architecture review audit: knowledge graph & information boundaries, observer snapshot pipeline, NPC AI state machines, save/load architecture, and map authoring pipeline. Each includes participants, key questions, input documents, and expected outputs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-11 21:36:02 +01:00
parent e1a3913060
commit 1920f002a1
6 changed files with 380 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Knowledge Graph & Information Boundaries Workshop Brief
+
+**Goal:** Design the knowledge data structure that replaces `InformationInventory { known_facts: Vec<String> }` — the pillar-1 mechanic foundation for asymmetric information.
+**Ticket:** #351 (epic)
+**Priority:** CRITICAL — Sprint 2 blocker
+**Participants:** Tyre (architecture lead), Gestalt (mechanics), Paula (narrative), Dudley (implementation), Qatux (docs), Si (tickets)
+**Source:** Architecture Review Audit 2026-02-11, Consensus Recommendation #12
+
+## Context
+
+The architecture audit independently identified the knowledge graph as the **most important and least specified critical system**. Both Tyre and Troblum rated it CRITICAL.
+
+D-010 principle 2 says: "every piece of game state is tagged with who knows it." The current implementation in `server/src/npc/mod.rs` has `InformationInventory { known_facts: Vec<String> }` — a placeholder that cannot support observation, monologue, dialogue, or success criteria.
+
+This system is load-bearing for:
+- D-010: Multiplayer-ready information boundaries
+- D-011: Fog of perception (what returns when you leave)
+- D-017: Perception modes (what different modes reveal)
+- D-028: Tagged line pools (access-tier dialogue)
+- D-033: Entity color from relationship state
+- Q-016: Knowledge hierarchy (`suspects` < `knows_of` < `knows_details`)
+
+## Key Questions to Resolve
+
+### Data Structure
+1. What does "entity A knows about entity B" look like as a Rust struct?
+2. How is knowledge confidence tracked? (Q-016: hierarchy levels)
+3. How does knowledge decay over time? (D-011: "fog returns when you leave")
+4. How are non-entity facts tracked? (locations, events, relationships between others)
+
+### Knowledge Flow
+5. How does knowledge enter the graph? (Direct observation, told by NPC, inferred)
+6. How does the `KnowledgeSource` affect confidence?
+7. Can knowledge be wrong? (Misinformation, outdated information)
+8. How do NPCs share knowledge with each other? (Gossip, reports, investigations)
+
+### Performance
+9. At 80 Active NPCs, each knowing about ~50 entities, what's the memory budget?
+10. How is the knowledge graph queried efficiently for observer snapshot generation?
+11. Does knowledge graph update need spatial partitioning? (Only update knowledge for nearby entities)
+
+### Game Mechanics Integration
+12. How does the knowledge graph drive monologue triggers? (D-019, tickets #119-122)
+13. How does knowledge state affect dialogue access tiers? (D-028)
+14. How do social triangles interact with knowledge? (Does knowing about a triangle change behavior?)
+
+## Input Documents
+
+| Document | What to read | Why |
+|----------|-------------|-----|
+| `decisions/perception.md` | D-011, D-015-D-019 | Perception system requirements |
+| `decisions/architecture.md` | D-010 (principles), D-024 (NPC model), D-026 (simulation tiers) | Architecture constraints |
+| `decisions/content.md` | D-028 (tagged line pools), D-033 (entity color) | Content system dependencies |
+| `decisions/questions.md` | Q-016 (knowledge hierarchy), Q-017 (triangle pressure) | Open questions this workshop should resolve |
+| `server/src/npc/mod.rs` | Current NPC component model | What exists today |
+| `server/src/perception/mod.rs` | Perception plugin stub | Where this code will live |
+| `docs/audits/architecture-review-2026-02-11.md` | Tyre R-01, Troblum section 4 | Detailed analysis and proposals |
+
+## Expected Outputs
+
+1. **Decision: D-0XX — Knowledge Graph Data Model** — Rust struct definitions for `KnowledgeGraph`, `EntityKnowledge`, `KnowledgeConfidence`, `KnowledgeSource`
+2. **Decision: Resolution of Q-016** — Knowledge hierarchy levels with concrete enum values
+3. **Design document:** Knowledge flow specification (how knowledge enters, propagates, decays)
+4. **Tickets:** Implementation tasks broken down from the design
+5. **Performance budget:** Memory and query time targets at 80 NPCs
+
+## Workshop Format
+
+Two rounds, following project convention:
+- **Round 1:** Each participant independently analyzes the questions from their domain perspective
+- **Round 2:** Cross-review, debate, and synthesis into concrete decisions