Exploration 00 — Frame¶
Status: living working doc — exploration track, session 0 Started: 2026-07-25 Owner: Giorgos + Claude sessions Protocol: one memo per session under
docs/plan/exploration/. Every memo ends with a Decided / Parked / Killed ledger so discussions accumulate instead of evaporating. No new feature development starts until this track produces a phase definition.
Why this track exists¶
Phases 0–6b delivered a technically mature stack — auth/RLS multi-tenancy, four hazards,
provenance, observability, an admin panel, 486+ tests — against a goal document
(plan.md "Extended End Goal") that was written before the product direction was
validated with anyone. The code outran the goal. Symptoms:
- Five personas named, none prioritized; the MVP slice is deliberately role-agnostic — i.e. aimed at nobody in particular.
- Phase gates measure "N items closed", never "a user did X". No adoption, usage, or revenue criterion exists anywhere.
- The stated business model (open-source Apache, managed hosting) matches neither current reality (all repos private) nor current intent (commercial licensing under evaluation).
Verdict adopted in session 0: what exists is a mature PoC of a platform, not yet a product. The exploration track's job is to converge on the goal before spending more development hours. This replaces "No phase is active" as the current state of the plan.
The core diagnosis (session 0)¶
The platform is scenario-centric: pick datasets → configure → enqueue job → poll → read EP curve. That is the researcher's question shape ("what happens if…?"). Three of the four target personas ask a location-centric question — "what is the risk here?" (this property, this portfolio, this municipality) — and expect an instant answer, not a job.
Market evidence (see 01-market-scan.md and the UI-focused scan in the RAT repo,
docs/plan/ui-revamp.md): the strongest products (First Street, Munich Re on-demand,
Climate X, XDI) are answer-first — address in, score out, sub-second, no parameter
panel. Parameters became curated defaults; compute happened before the user arrived.
Implication (the deepest available maturation step, architectural not cosmetic): a precomputed risk surface + query layer on top of the existing batch pipeline.
- The existing pipeline becomes the factory: national-scale scenario runs computed offline, per hazard × scenario × horizon.
- A new read path serves instant lookups: geocode → cell / building → precomputed scores → explainability drawer.
- The batch/job path remains the researcher/analyst surface; it is not replaced.
The granularity ladder¶
Today the risk-object ladder has two rungs: dataset and exposure point. The target ladder: country → admin unit → portfolio → asset. Missing rungs:
- Asset as a first-class entity (address, footprint, attributes, per-hazard scores, history) — not just a row in an uploaded exposure CSV.
- Admin-unit rollups as risk objects you can query and report on — GADM + zoom aggregation exist today for rendering only.
- Portfolio as primary workbench object (an insurer's book of business, with accumulation and what-if), not a grouping-with-weighted-average over exposures.
Personas — jobs to be done vs. what exists¶
| Persona | Job to be done | Have today | Missing product |
|---|---|---|---|
| Insurer | Price and manage a book; justify premiums to customers | EP curve, PML, deductible/cover, portfolios (basic), multi-tenancy | Portfolio workbench (accumulation, what-if, per-asset scores); claims-data calibration; B2B2C embed — a white-label risk card the insurer shows their customer ("insurance culture" = a distinct deliverable, not a UI mode) |
| Citizen | "Is my house at risk?" | Nothing citizen-shaped | Address-first funnel (First Street pattern): search → multi-hazard score card → plain-language deep-dive → mitigation tips. Needs geocoding + precomputed surface. Doubles as the marketing engine and the public-private angle |
| Decision-maker | Defend a budget/policy decision | Cost-benefit, adaptation measures, GADM layers, CSV/PDF stub | Admin-unit risk profiles + report composer (FEMA NRI pattern): pick unit → composed dossier; compare two units; pre/post-adaptation narrative. For this persona reports are the product |
| Researcher | Test models without code | Scenario wizard, provenance stamps, impact-fn viz, parity harness | The model lab: edit/upload vulnerability curves; same scenario through two engines side-by-side (adapter work enables this — no competitor offers multi-model consensus); uncertainty bands; one-click reproducibility bundle |
Shared primitives (build once, lens four ways)¶
- Score/rating layer — ordinal grades (A–F / 1–10 / RAG) rolled up from raw EAD/EP, per asset, portfolio, and admin unit. Every credible product in the scan does this; raw € values remain one drill-down below.
- Explainability drawer — "why this score": contributing hazard, curve, dataset, assumptions. The provenance system already carries ~80 % of the substance.
- Report composer — any object (asset / portfolio / admin unit / scenario) → composed PDF with maps, charts, tables, comparison mode.
- Location-first entry — geocoding + search as the front door; upload as the power path.
Candidate areas surfaced but not yet explored¶
- Historical-event validation as a feature — observed-events layer beside modelled risk ("here's what the model said, here's what happened"). Model credibility is the #1 open point raised by every stakeholder conversation to date.
- Claims-data calibration — insurer uploads loss history to locally calibrate curves. High value, high moat; converts the data-partnership question into a product feature.
- Forecast-driven alerting — realistic first rung of the live-risk idea: open forecast feeds (EFAS/GloFAS) × portfolio footprints → alerts. Buildable on the batch stack + a poller. IoT/live telemetry becomes rung two, later.
- The API/SDK as a product — banks/consultants embedding scores (Fathom dual-track pattern). SDK exists, unpublished.
- Country/data packs — pre-processed regional hazard bundles as the productized form of the old "data marketplace" idea; aligns with the config-bundle model.
Track roadmap¶
| Session | Memo | Purpose | Exit |
|---|---|---|---|
| 0 | 00-frame.md |
Frame, diagnosis, personas, protocol | this doc |
| 1 | 01-market-scan.md |
Business/technical/architecture scan (Claude, web research) ∥ manual UI + business-idea scan (Giorgos) | competitor map, white spots confirmed/killed |
| 2 | 02-personas.md |
Pick the primary persona; define the score layer & entry surface for it | one persona ranked #1, others sequenced |
| 3 | 03-goal.md |
Rewrite plan.md Extended End Goal: goal, personas, success criteria, business model; licensing posture recorded as deferred pending persona validation |
plan.md PR |
| 4 | 04-answer-layer-rfc.md |
Architecture RFC: precomputed surface, Asset entity, granularity ladder, scores | ADR candidates |
| 5+ | — | Phase definition for the first product phase; then /phase-split |
issues |
Cadence: recurring sessions, no fixed clock; a session ends with its ledger updated.
Decided / Parked / Killed (session 0)¶
Decided
- Exploration track lives in this repo under docs/plan/exploration/; memo-per-session
with this ledger discipline.
- "Mature PoC, goal reset needed" is the accepted framing; no new feature development
until the track yields a phase definition.
- Scenario-centric vs location-centric is the accepted core diagnosis; the precomputed
answer layer is the leading architectural thesis (to be tested in 01/02/04).
- Four target personas: insurer, citizen, decision-maker, researcher (priority TBD in 02).
- Market scan split: Claude runs the business/technical/architecture scan; Giorgos runs
the manual UI-pattern + business-idea scan in parallel.
Parked - Licensing/relicensing decision — explicitly deferred until after persona validation (session 2/3). Currently: engine public Apache-2.0 on PyPI; backbone/UI private. - IoT / live-telemetry risk — parked behind forecast-driven alerting. - Desktop surface, data marketplace beyond country packs, managed hosting — remain parked as before. - Phase 7 as written — its adapter items (7.1, 7.3) are likely dual-use keepers; its public-facing items (7.6 marketing site, 7.9 privacy banner) wait on licensing. Re-cut after session 3.
Killed - Nothing yet.