| # Reality Divergence — v2 Roadmap |
|
|
| The hackathon build is intentionally lean: two explicit tabs, schema-driven |
| generation, validation + fallbacks, and one atmospheric image per result. This |
| document parks the larger **routed, schema-driven architecture** as the post- |
| hackathon direction. Nothing here is required for the current submission. |
|
|
| ## Guiding idea |
|
|
| Move from "two fixed tabs" to a **router → policy gate → prompt picker → |
| structured generation → validation → renderer** pipeline. Routing is decided in |
| *code*, never by the model picking its own route. |
|
|
| ## Where we already are (≈55% of the target) |
|
|
| | Target capability | Status | |
| |---|---| |
| | Schema-driven structured generation | ✅ done (`prompts.py` + parsing in `app.py`) | |
| | Per-intent output schemas | ✅ done (timeline ≈ reflection; world ≈ alt-history/fork) | |
| | Validation + never-crash fallback | ✅ done (`safe_int/str/list`, curated fallbacks) | |
| | Timeline / branch renderer | ✅ done (HTML spine, better/worse, winners/losers) | |
| | Safety guardrail (personal tab) | ✅ done (risk gate + 988 notice) | |
| | Uncertainty framing | 🟡 in prompts + a "speculative" badge; no per-claim tagging | |
| | Prompt picker | 🟡 by tab, not by router (2 routes, not 9) | |
| | Intent router + confidence + clarification | ❌ not built | |
| | Tone/mode selectors, confidence indicator | ❌ not built | |
| | Streaming staged output | ❌ not built | |
| | Conversational follow-up (turn-taking) | 🟡 reflection question shown statically | |
|
|
| ## v2 backlog (priority order) |
|
|
| 1. **Intent router** — one lightweight model (or rules) call classifying input into |
| a taxonomy: `personal_regret`, `alternate_history`, `event_counterfactual`, |
| `global_shock`, `regional_disaster`, `civilizational_fork`, `comparison`, |
| `creative_weird`, `mixed`. Returns `primary_intent`, `secondary_intents`, |
| `confidence`, `needs_clarification`, `divergence_scale`, `tone`, `image_policy`. |
| 2. **Policy gate** — below a confidence threshold (~0.72) ask one clarifying |
| question instead of generating; decide allowed output type. |
| 3. **Per-claim epistemic tagging** — tag statements `certain | speculative | |
| assumption`; render badges; downgrade tone when the model is over-confident. |
| 4. **Image policy** — generate images only for `creative_weird` / explicit visual |
| requests, not for reflective/uncertain output. (Current build always shows one |
| decorative banner — revisit.) |
| 5. **Single prompt box + mode/tone selectors + confidence indicator** to replace |
| the two-tab split. |
| 6. **Streaming** the response in stages (intent → structure → text → timeline → |
| image) so it feels fast. |
| 7. **Retry-once on schema-validation failure** before falling back. |
| 8. **Strict validation** via Pydantic/JSON-schema instead of the current `safe_*` |
| coercion. |
|
|
| ## Known design tensions to decide in v2 |
|
|
| - **Images:** v2 spec says default-off, artifact-only. Current build shows one |
| text-free atmospheric banner per result (decorative, not informational). |
| - **Visual style:** v2 spec favors restraint ("no chaotic gradients, reflective |
| instrument"). Current build uses an animated gradient hero for impact. |
|
|
| ## Reference |
|
|
| Architecture spec drafted from the Build Small field guide constraints and a |
| prompt-routing / structured-output design pass (June 2026). |
|
|
