| 1 | # World Modeling Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | Meta-playbook for keeping knowledge structure faithful to reality: intuition first, formalization second. |
| 5 | |
| 6 | ## Scope |
| 7 | - Domain/world boundary decisions |
| 8 | - Separation of similar-but-distinct ecosystems |
| 9 | - Router-layer vs world-layer architecture |
| 10 | - Ongoing correction when reality disproves structure |
| 11 | |
| 12 | ## Core Principle |
| 13 | - Do not force reality into a preselected schema. |
| 14 | - Let distinctions emerge from lived behavior, failures, and diagnostic practice. |
| 15 | |
| 16 | ## Intuition-First Loop |
| 17 | - Sense: identify where context "feels different" in causality, language, and action patterns. |
| 18 | - Probe: run one concrete scenario to test whether that difference is operationally real. |
| 19 | - Separate: if behavior diverges, keep worlds separate even when labels look similar. |
| 20 | - Bridge: connect worlds through router layers, not by merging world layers. |
| 21 | - Recalibrate: if evidence contradicts the map, update the map immediately. |
| 22 | |
| 23 | ## What Counts as a Separate World |
| 24 | - Different causal model of how things work. |
| 25 | - Different dominant failure modes. |
| 26 | - Different verification/diagnostic workflow. |
| 27 | - Different vocabulary that cannot be safely collapsed. |
| 28 | |
| 29 | ## What Belongs to a Router (Not a World) |
| 30 | - Tool choice guidance. |
| 31 | - Shared safety constraints. |
| 32 | - Cross-world interoperability rules. |
| 33 | - Navigation/index links. |
| 34 | |
| 35 | ## Anti-Patterns |
| 36 | - Premature unification "for convenience". |
| 37 | - Grouping by surface similarity (same category labels) despite behavioral divergence. |
| 38 | - Turning uncertain intuition into rigid ontology too early. |
| 39 | - Repeating known misclassification because "it looks cleaner". |
| 40 | |
| 41 | ## Recovery Protocol After Misclassification |
| 42 | - Split immediately when divergence is confirmed. |
| 43 | - Move shared pieces to router layer. |
| 44 | - Keep each world internally coherent and testable. |
| 45 | - Record one concise "why split happened" note for future intuition calibration. |
| 46 | |
| 47 | ## Metrics |
| 48 | - Number of re-splits caused by over-merging. |
| 49 | - Time to correct wrong categorization. |
| 50 | - Cross-world incident confusion rate. |
| 51 | - Stability of world boundaries over real project cycles. |
| 52 | |
| 53 | ## Revisit Triggers |
| 54 | - Frequent "this feels wrong" feedback during categorization. |
| 55 | - Repeated incidents where one playbook fails in one of the grouped ecosystems. |
| 56 | - Rising ambiguity in ownership of diagnostics and decisions. |
| 57 | |
| 58 | ## Calibration Examples (Fast Intuition Check) |
| 59 | |
| 60 | ### Example 1: Windows vs Linux |
| 61 | - Surface similarity: both are "OS environment troubleshooting". |
| 62 | - Divergence signal: service model, permissions, process lifecycle, and diagnostics toolchain differ materially. |
| 63 | - Decision: two worlds (`windows-environments`, `linux-environments`) + optional router bridge. |
| 64 | |
| 65 | ### Example 2: Regex vs Parser Logic |
| 66 | - Surface similarity: both "extract structure from text". |
| 67 | - Divergence signal: regex is pattern-matching with dialect/overmatch risks; parser logic is grammar/model-driven with different failure surfaces. |
| 68 | - Decision: keep regex as its own world; parser architecture belongs to another world (language/data tooling), linked via router. |
| 69 | |
| 70 | ### Example 3: Docker vs Host Runtime |
| 71 | - Surface similarity: both "runtime and operations". |
| 72 | - Divergence signal: container isolation, image lifecycle, volume/network boundary, and security model introduce distinct causal chains. |
| 73 | - Decision: keep Docker world separate from host-OS worlds; connect through deployment/ops router contracts. |
| 74 | |
| 75 | ### Example 4: Blazor vs Avalonia/XAML |
| 76 | - Surface similarity: both are ".NET UI". |
| 77 | - Divergence signal: runtime model (web vs desktop/native shell), rendering lifecycle, state/navigation contracts, deployment and diagnostics differ. |
| 78 | - Decision: keep separate UI worlds with shared frontend router patterns only where behavior is truly equivalent. |
| 79 | |
| 80 | ### Example 5: Roslyn Code Actions vs Manual Edits |
| 81 | - Surface similarity: both can produce the same textual code change. |
| 82 | - Divergence signal: Roslyn is symbol/semantic aware, while manual edits are text-level and can miss references/overloads/renames. |
| 83 | - Decision: keep semantic refactoring workflow as its own tooling world; manual patching remains a fallback world with stricter verification. |
| 84 | |
| 85 | |