docs: Decision Model v1.0 — Evidence-backed decisions + explainability + validation scenarios
- 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.
This commit is contained in:
Bernt
@@ -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**
|
||||
Reference in New Issue
Block a user