From ff136e8aae5ee25dc7d2eeb88caaa9439831ebc7 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 11:59:33 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20Decision=20Model=20v1.0=20=E2=80=94=20E?= =?UTF-8?q?vidence-backed=20decisions=20+=20explainability=20+=20validatio?= =?UTF-8?q?n=20scenarios?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Six layers (added Evidence between Observation and Finding): 1. Reality 2. Observation 3. Evidence (linked observations with context) 4. Finding 5. Decision 6. Business Impact - Decision Object restructured: 1. Decision — what should user decide? 2. Why — why system recommends this 3. Evidence — what observations support this 4. Confidence — how certain (3 dimensions) 5. Consequence — what if nothing done 6. Action — next step 7. Business Impact — economic/operational meaning - Confidence Model (3 dimensions): - Observation Confidence: how certain is detection? - Evidence Strength: how strongly supported? - Recommendation Confidence: how certain is recommendation? - Explainability Principle: - Every Decision Card must be explorable - User can click: Decision → Finding → Evidence → Observations → Reality - Competitive advantage: traceability to source material - Business Impact Model (4 dimensions): - Risk, Cost, Time, Opportunity - Three validation scenarios: 1. Road Crack — simple, common 2. Damaged Facade — complex, critical 3. Broken Road Sign — simple, regulatory - Pass criteria: Same Decision Object works for all three Rationale: Decision Intelligence, not BI. Evidence-backed decisions are the core product. Explainability is competitive advantage. Validation against real scenarios before freezing. --- docs/design/DECISION_MODEL_v1.0.md | 269 +++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 docs/design/DECISION_MODEL_v1.0.md diff --git a/docs/design/DECISION_MODEL_v1.0.md b/docs/design/DECISION_MODEL_v1.0.md new file mode 100644 index 000000000..9ff42ef01 --- /dev/null +++ b/docs/design/DECISION_MODEL_v1.0.md @@ -0,0 +1,269 @@ +# DECISION MODEL v1.0 + +**The Core Product of Landvex** + +| | | +|---|---| +| **Version** | 1.0 | +| **Status** | DRAFT | +| **Scope** | All Landvex decisions, dashboards, reports, APIs | + +--- + +## The Six Layers + +``` +Layer 1: Reality + (sensors, mobile, video, GIS, drones) + ↓ +Layer 2: Observation + ("crack detected", "road surface degraded") + ↓ +Layer 3: Evidence + (linked observations with context) + ↓ +Layer 4: Finding + ("area has deteriorated since last inspection") + ↓ +Layer 5: Decision + ("prioritize inspection within 14 days") + ↓ +Layer 6: Business Impact + ("risk reduced", "cost avoided", "revenue created") +``` + +--- + +## Layer 1: Reality + +**Input sources:** +- Mobile phones (quiXzoom) +- Drones +- Fixed cameras +- Sensors +- GIS data +- Satellite imagery + +**Principle:** Reality is the only source of truth. + +--- + +## Layer 2: Observation + +**Definition:** A single recorded fact from reality. + +**Example:** +``` +Observation: +- Type: "crack" +- Location: [lat, lng] +- Timestamp: 2026-07-02T10:00:00Z +- Source: quiXzoom mobile +- Media: [photo_url, video_url] +- Observation Confidence: 0.94 +``` + +--- + +## Layer 3: Evidence + +**Definition:** Linked observations with context, forming a body of proof. + +**Example:** +``` +Evidence: +- Description: "Multiple cracks observed in Sector 7" +- Observations: [observation_1, observation_2, observation_3] +- Evidence Strength: 0.91 +- Consistency: "All observations confirm degradation" +- Time Span: "2026-06-15 to 2026-07-02" +``` + +## Layer 4: Finding + +**Definition:** A pattern or conclusion derived from evidence. + +**Example:** +``` +Finding: +- Description: "Road surface has degraded 15% since last inspection" +- Area: "Nacka Municipality, Sector 7" +- Evidence: [evidence_1, evidence_2] +- Finding Confidence: 0.87 +- Trend: "deteriorating" +``` + +--- + +## Layer 5: Decision + +**Definition:** An evidence-backed recommended action. + +### Decision Object + +Every decision must contain: + +| # | Field | Description | Example | +|---|-------|-------------|---------| +| 1 | **Decision** | What should the user decide? | "Prioritize inspection" | +| 2 | **Why** | Why does the system recommend this? | "Road surface degraded 15%" | +| 3 | **Evidence** | What observations support this? | [evidence_1, evidence_2] | +| 4 | **Confidence** | How certain is the model? | See Confidence Model below | +| 5 | **Consequence** | What happens if nothing is done? | "Risk of accident increases" | +| 6 | **Action** | What is the next step? | "Schedule inspection" | +| 7 | **Business Impact** | What does this mean economically/operationally? | See Business Impact Model below | + +### Confidence Model + +| Dimension | Description | Example | +|-----------|-------------|---------| +| **Observation Confidence** | How certain is the detection? | "94% — clear visual evidence" | +| **Evidence Strength** | How strongly does evidence support the conclusion? | "91% — three consistent observations" | +| **Recommendation Confidence** | How certain is the recommendation? | "87% — historical data supports this action" | + +### Explainability + +**Every Decision Card must be explorable:** + +``` +Decision + ↓ (click) +Finding + ↓ (click) +Evidence + ↓ (click) +Observations + ↓ (click) +Reality +``` + +The user must be able to click all the way back to source material. + +--- + +## Layer 6: Business Impact + +**Definition:** The measurable effect of the decision on the business. + +| Type | Metric | Example | +|------|--------|---------| +| **Risk** | Probability × Severity | "High — accident risk 12% → 3%" | +| **Cost** | Currency | "$50,000 in emergency repairs avoided" | +| **Time** | Duration | "Action required within 14 days" | +| **Opportunity** | Business value | "Plan maintenance with nearby works" | + +--- + +## Decision Card + +**Visual representation:** + +``` +┌─────────────────────────────────────┐ +│ Area Score: 87 │ +│ ▼ │ +│ │ +│ 3 Important Decisions │ +│ ┌─────────────────────────────────┐ │ +│ │ ⚠️ Road surface degraded │ │ +│ │ Confidence: 87% │ │ +│ │ Priority: High │ │ +│ │ Recommend: Inspect in 14d │ │ +│ │ If ignored: Safety risk ↑ │ │ +│ │ Next step: Schedule now │ │ +│ │ Evidence: 12 observations │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ Map │ +│ │ +│ Evidence │ +│ │ +│ History │ +└─────────────────────────────────────┘ +``` + +--- + +## Verification + +For every decision: +- [ ] Decision — what should the user decide? +- [ ] Why — why does the system recommend this? +- [ ] Evidence — what observations support this? +- [ ] Confidence — how certain is the model? (observation, evidence, recommendation) +- [ ] Consequence — what happens if nothing is done? +- [ ] Action — what is the next step? +- [ ] Business Impact — what does this mean economically/operationally? +- [ ] Explainability — can the user click back to source material? + +## Validation Scenarios + +Before freezing Decision Model v1.0, validate against three real scenarios: + +### Scenario 1: Road Crack + +| Layer | Example | +|-------|---------| +| Reality | Mobile photo of road crack | +| Observation | "Crack detected, 15cm width" | +| Evidence | 3 observations of cracks in same area | +| Finding | "Road surface degraded 15% since last inspection" | +| Decision | "Prioritize inspection within 14 days" | +| Business Impact | Risk: High, Cost: $50k avoided, Time: 14 days, Opportunity: Plan with nearby works | + +### Scenario 2: Damaged Facade + +| Layer | Example | +|-------|---------| +| Reality | Drone video of building facade | +| Observation | "Facade panel loose, 30cm displacement" | +| Evidence | 2 observations + weather data | +| Finding | "Facade integrity compromised, risk of falling debris" | +| Decision | "Immediate safety inspection required" | +| Business Impact | Risk: Critical, Cost: $200k liability, Time: 24 hours, Opportunity: Prevent injury | + +### Scenario 3: Broken Road Sign + +| Layer | Example | +|-------|---------| +| Reality | Mobile photo of damaged sign | +| Observation | "Stop sign damaged, 50% visibility" | +| Evidence | 1 observation + traffic data | +| Finding | "Traffic control compromised at intersection" | +| Decision | "Replace sign within 48 hours" | +| Business Impact | Risk: Medium, Cost: $5k fine avoided, Time: 48 hours, Opportunity: Standard replacement | + +**Pass criteria:** Same Decision Object works for all three without modification. + +--- + +## Relationship to Dashboard + +**Dashboard is not:** 120 widgets +**Dashboard is:** Decision Card visualization + +``` +Area Score + ↓ +Top 3 Decisions + ↓ +Map + ↓ +Evidence + ↓ +History +``` + +--- + +## ändringshistoria + +| Version | Datum | Beskrivning | +|---------|-------|-------------| +| 1.0 | 2026-07-02 | Initial decision model with six layers, evidence-backed decisions, explainability, confidence model, validation scenarios | + +--- + +## STATUS + +**DRAFT — Awaiting validation against three scenarios**