platform-admin/boc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Decision Pipeline v1.0 + Learning Loop + Control Intelligence + 3 Customer Cases

Browse Source 
- Added Step 7: Learning (feedback loop from Business Impact to Intelligence)
- Control Intelligence definition: LandveX produces Control Intelligence, not AI
- Three target customer cases defined:
  1. Municipality — Inspect or wait? (Maintenance prioritization)
  2. Property Owner — Repair now or plan later? (Cost vs risk)
  3. Contractor/Operations — Which action first? (Operational planning)
- Validation requirements: Run each case through full pipeline, document breaks,
  revise only after data contradicts model
- Communication principle: Observation → Analysis → Recommendation
  (AI is implementation, recommendation is product)

Rationale: Stop modeling, start observing. Model changes when data contradicts
it, not before. Three real customer cases before freezing.
This commit is contained in:
Bernt
2026-07-02 12:13:25 +00:00
parent e3e70c52d4
commit f05fded74e
3 changed files with 627 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/DECISION_MODEL_REVIEW.md
+217
View File
@@ -0,0 +1,217 @@
# DECISION MODEL v1.0 — MANUAL REVIEW
**Validation of 8 Scenarios Against Decision Object Structure**
| | |
|---|---|
| **Version** | 1.0 |
| **Date** | 2026-07-02 |
| **Reviewer** | AI Agent |
| **Rule** | No changes to model during review |
---
## Review Protocol
For each scenario, answer:
| # | Control | Question | Result |
|---|---------|----------|--------|
| 1 | **Decision** | Is this a real decision, not just an observation? | Yes / No |
| 2 | **Verb** | Can the decision be expressed as a verb? | Yes / No |
| 3 | **Information** | Is more information needed before deciding? | Yes / No |
| 4 | **Decision Object** | Are all 7 fields used? | List unused |
| 5 | **Missing Fields** | Is anything missing? | List missing |
| 6 | **Explainability** | Can the chain Reality → Observation → Evidence → Finding → Decision be followed? | Yes / No |
| 7 | **Domain Object** | Does the Decision Object reference at least one concrete domain object? | Yes / No |
| 8 | **Outcome** | Pass / Observation / Fail | |
---
## Scenario 1: Road Crack (Maintenance)
| # | Control | Result | Notes |
|---|---------|--------|-------|
| 1 | Decision | ✅ Yes | "Prioritize inspection" is a decision |
| 2 | Verb | ✅ Yes | "Inspect" |
| 3 | Information | ✅ No | All needed info present |
| 4 | Decision Object | ✅ All used | Decision, Why, Evidence, Confidence, Consequence, Action, Business Impact |
| 5 | Missing Fields | ✅ None | |
| 6 | Explainability | ✅ Yes | Photo → crack detected → 3 observations → degraded 15% → inspect |
| 7 | Domain Object | ✅ Yes | "Road 1132" |
| 8 | **Outcome** | **✅ PASS** | |
---
## Scenario 2: Damaged Facade (Safety)
| # | Control | Result | Notes |
|---|---------|--------|-------|
| 1 | Decision | ✅ Yes | "Immediate safety inspection" is a decision |
| 2 | Verb | ✅ Yes | "Inspect" (urgent) |
| 3 | Information | ✅ No | All needed info present |
| 4 | Decision Object | ✅ All used | All 7 fields |
| 5 | Missing Fields | ✅ None | |
| 6 | Explainability | ✅ Yes | Drone video → panel loose → weather data → integrity compromised → immediate inspection |
| 7 | Domain Object | ✅ Yes | "Building A7" |
| 8 | **Outcome** | **✅ PASS** | |
---
## Scenario 3: Broken Road Sign (Compliance)
| # | Control | Result | Notes |
|---|---------|--------|-------|
| 1 | Decision | ✅ Yes | "Replace sign" is a decision |
| 2 | Verb | ✅ Yes | "Replace" |
| 3 | Information | ✅ No | All needed info present |
| 4 | Decision Object | ✅ All used | All 7 fields |
| 5 | Missing Fields | ✅ None | |
| 6 | Explainability | ✅ Yes | Photo → sign damaged → traffic data → control compromised → replace |
| 7 | Domain Object | ✅ Yes | "Intersection X" |
| 8 | **Outcome** | **✅ PASS** | |
---
## Scenario 4: Vegetation Blocking Sight (Risk Reduction)
| # | Control | Result | Notes |
|---|---------|--------|-------|
| 1 | Decision | ✅ Yes | "Schedule vegetation removal" is a decision |
| 2 | Verb | ✅ Yes | "Remove" |
| 3 | Information | ✅ No | All needed info present |
| 4 | Decision Object | ✅ All used | All 7 fields |
| 5 | Missing Fields | ✅ None | |
| 6 | Explainability | ✅ Yes | Photos → vegetation high → growth trend → degradation → schedule removal |
| 7 | Domain Object | ✅ Yes | "Intersection Y" |
| 8 | **Outcome** | **✅ PASS** | |
---
## Scenario 5: Parking Area Wear (Investment Priority)
| # | Control | Result | Notes |
|---|---------|--------|-------|
| 1 | Decision | ✅ Yes | "Include in budget" is a decision |
| 2 | Verb | ✅ Yes | "Include" / "Budget" |
| 3 | Information | ⚠️ Observation | May need cost estimate for full decision |
| 4 | Decision Object | ✅ All used | All 7 fields |
| 5 | Missing Fields | ⚠️ Observation | "Cost estimate" could strengthen decision |
| 6 | Explainability | ✅ Yes | Photos → wear → usage data → need resurfacing → budget |
| 7 | Domain Object | ✅ Yes | "Parking Area Z" |
| 8 | **Outcome** | **⚠️ OBSERVATION** | Decision valid but could be strengthened with cost estimate |
---
## Scenario 6: Cosmetic Scratch (No Action)
| # | Control | Result | Notes |
|---|---------|--------|-------|
| 1 | Decision | ✅ Yes | "No action, continue monitoring" is a conscious decision |
| 2 | Verb | ✅ Yes | "Monitor" |
| 3 | Information | ✅ No | All needed info present |
| 4 | Decision Object | ✅ All used | All 7 fields |
| 5 | Missing Fields | ✅ None | |
| 6 | Explainability | ✅ Yes | Photo → scratches → no functional impact → normal wear → monitor |
| 7 | Domain Object | ✅ Yes | "Sign S15" |
| 8 | **Outcome** | **✅ PASS** | |
---
## Scenario 7: Mixed Evidence Sources (Complex)
| # | Control | Result | Notes |
|---|---------|--------|-------|
| 1 | Decision | ✅ Yes | "Inspect drainage, prioritize if recurs" is a decision |
| 2 | Verb | ✅ Yes | "Inspect" / "Prioritize" |
| 3 | Information | ✅ No | All needed info present |
| 4 | Decision Object | ✅ All used | All 7 fields |
| 5 | Missing Fields | ✅ None | |
| 6 | Explainability | ✅ Yes | Photo + sensor + weather → pooling → historical data → drainage inadequate → inspect |
| 7 | Domain Object | ✅ Yes | "Road Segment R42" |
| 8 | **Outcome** | **✅ PASS** | |
---
## Scenario 8: Insufficient Evidence (No Recommendation)
| # | Control | Result | Notes |
|---|---------|--------|-------|
| 1 | Decision | ⚠️ Observation | "No recommendation yet" is not a decision, it's a deferral |
| 2 | Verb | ⚠️ Observation | "Collect" is an action, not a final decision |
| 3 | Information | ✅ Yes | More data needed |
| 4 | Decision Object | ⚠️ Observation | "Consequence" and "Business Impact" are weak |
| 5 | Missing Fields | ⚠️ Observation | "Confidence" is low by definition — could be explicit |
| 6 | Explainability | ✅ Yes | Blurry photo → unclear → conflicting AI → inconclusive |
| 7 | Domain Object | ⚠️ Observation | Location unclear due to low GPS precision |
| 8 | **Outcome** | **⚠️ OBSERVATION** | Valid outcome but not a decision — model handles it correctly |
---
## Review Summary
| Metric | Count |
|--------|-------|
| **Total Scenarios** | 8 |
| **Pass** | 6 |
| **Observation** | 2 |
| **Fail** | 0 |
### Recurring Unused Fields
None. All 7 fields used across all scenarios.
### Recurring Missing Fields
- **Cost estimate** (Scenario 5) — could strengthen investment decisions
- **Explicit low confidence** (Scenario 8) — could clarify insufficient evidence
### Recurring Unclear Verbs
None. All decisions expressible as verbs.
### Domain Object References
| Scenario | Domain Object | Status |
|----------|--------------|--------|
| 1 | Road 1132 | ✅ |
| 2 | Building A7 | ✅ |
| 3 | Intersection X | ✅ |
| 4 | Intersection Y | ✅ |
| 5 | Parking Area Z | ✅ |
| 6 | Sign S15 | ✅ |
| 7 | Road Segment R42 | ✅ |
| 8 | (unclear GPS) | ⚠️ |
---
## Conclusion
**Recommendation: READY FOR INVARIANCE TEST**
The Decision Object structure handles all 8 scenarios without modification. Two scenarios generate observations (not failures) — the model correctly handles "insufficient evidence" and "needs more data" cases.
**No changes needed to Decision Model v1.0.**
---
## Next Steps
1. ✅ Manual Review — COMPLETE
2. ⏳ Decision Invariance Test — Ready to run
3. ⏳ Evidence Variation Test — Ready to run
4. ⏳ Empirical validation with real data — Pending
---
## ändringshistoria
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Manual review of 8 scenarios — 6 pass, 2 observation, 0 fail |
---
## STATUS
**REVIEW COMPLETE — READY FOR INVARIANCE TEST**
docs/design/DECISION_MODEL_v1.0.md
+141 -17
View File
@@ -34,6 +34,63 @@ Layer 6: Business Impact
--- ---
## Landvex Ontology
**All information is objects with relationships.**
### Core Objects
| Object | Description | Example |
|--------|-------------|---------|
| **Area** | Geographic region | "Nacka Municipality" |
| **Road** | Road segment | "Road 1132" |
| **Building** | Structure | "Building A7" |
| **Asset** | Infrastructure element | "Bridge C", "Drain B" |
| **Mission** | Data collection task | "Inspect Road 1132" |
| **Observation** | Recorded fact | "Crack detected" |
| **Evidence** | Linked observations | "3 cracks in Sector 7" |
| **Finding** | Pattern or conclusion | "Road degraded 15%" |
| **Decision** | Recommended action | "Inspect within 14 days" |
| **Action** | Executed task | "Inspection completed" |
| **Customer** | Organization | "Nacka Municipality" |
| **Contract** | Agreement | "Maintenance Contract 2026" |
### Core Relationships
```
Observation belongs_to Road
Road belongs_to Area
Area has_owner Customer
Decision created_from Finding
Finding supported_by Evidence
Evidence contains Observation
Mission produces Observation
Customer has Contract
Contract covers Area
```
### Example Object Network
```
Road 1132
├── Score: 67
├── belongs_to: Nacka Municipality
├── has_observations: [obs_1, obs_2, obs_3]
├── has_findings: [finding_1]
├── has_decisions: [decision_1]
└── history:
├── 2024: Score 72
├── 2025: Score 70
└── 2026: Score 67
```
**Dashboard shows objects, not data.**
**Not:** "Cracks: 142"
**But:** "Road 1132 → Score 67 → 5 new observations → 3 confirmed cracks → Risk increased 14% → Recommendation: Inspect within 30 days"
---
## Layer 1: Reality ## Layer 1: Reality
**Input sources:** **Input sources:**
@@ -291,6 +348,21 @@ Before freezing Decision Model v1.0, validate against diverse scenarios:
**Decision type:** Complex — "Multiple evidence sources converging" **Decision type:** Complex — "Multiple evidence sources converging"
### Scenario 8: Insufficient Evidence (No Recommendation)
| Layer | Example |
|-------|---------|
| Reality | Blurry mobile photo, low GPS precision |
| Observation | "Possible crack, unclear image" |
| Evidence | 1 low-quality observation, conflicting AI models, old data |
| Finding | "Inconclusive — cannot determine severity" |
| Decision | "No recommendation yet. Collect more data." |
| Business Impact | Risk: Unknown, Cost: $0, Time: Re-inspect, Opportunity: None |
**Decision type:** Insufficient evidence — "We don't know yet"
**Note:** This is different from "No action needed". "No action" means we know enough to wait. "Insufficient evidence" means we don't know enough to recommend anything.
--- ---
## Decision Invariance Test ## Decision Invariance Test
@@ -334,15 +406,46 @@ Before displaying any decision to the user:
--- ---
## Decision Verb Rule
**Every decision must be expressible as a verb.**
| Verb | Meaning | Example |
|------|---------|---------|
| **Inspect** | Verify condition | "Inspect Road A12" |
| **Repair** | Fix immediately | "Repair Drain B" |
| **Prioritize** | Schedule soon | "Prioritize resurfacing" |
| **Monitor** | Watch and wait | "Monitor Bridge C" |
| **Wait** | Conscious inaction | "No action needed, continue monitoring" |
| **Escalate** | Higher authority needed | "Escalate to safety team" |
| **Ignore** | No action, no monitoring | "False positive, ignore" |
| **Collect** | Need more data | "Collect more evidence" |
**If a Decision Object cannot be summarized with a clear action verb, it is still analysis, not a decision.**
## Manual Review Checklist
Before running Invariance Test, manually review each scenario:
| Question | Check |
|----------|-------|
| Is this really a decision, not just an observation? | |
| Does the decision-maker need more information? | |
| Is any Decision Object field unused? | |
| Is any field missing across scenarios? | |
| Can the decision be expressed as a verb? | |
## Pass Criteria ## Pass Criteria
**Decision Model v1.0 is validated when:** **Decision Model v1.0 is validated when:**
1. All 7 scenarios produce valid Decision Objects 1. All 8 scenarios produce valid Decision Objects
2. Decision Invariance Test passes 2. Manual review passes for all scenarios
3. Evidence Variation Test passes 3. Decision Invariance Test passes
4. Decision Quality Gate passes for all scenarios 4. Evidence Variation Test passes
5. "No action" scenario works correctly 5. Decision Quality Gate passes for all scenarios
6. "No action" and "Insufficient evidence" scenarios both work correctly
7. All decisions can be expressed as verbs
**Status:** ⏳ Pending validation **Status:** ⏳ Pending validation
@@ -351,30 +454,51 @@ Before displaying any decision to the user:
## Relationship to Dashboard ## Relationship to Dashboard
**Dashboard is not:** 120 widgets **Dashboard is not:** 120 widgets
**Dashboard is:** Decision Card visualization **Dashboard is:** Object visualization with decisions
``` ```
Area Score ──────────────────────────
↓ AREA SCORE
Top 3 Decisions 83
↓ ↑ +4
Map ──────────────────────────
↓ TOP DECISIONS
Evidence Inspect Road A12 [High]
↓ Repair Drain B [Medium]
History Monitor Bridge C [Low]
──────────────────────────
MAP
● ● ▲ ■
──────────────────────────
RECENT OBSERVATIONS
──────────────────────────
BUSINESS IMPACT
Risk ↓
Cost ↓
Time Saved ↑
──────────────────────────
``` ```
**Principle:** The user always feels the system helps them make decisions, not consume statistics.
--- ---
## ändringshistoria ## ändringshistoria
| Version | Datum | Beskrivning | | Version | Datum | Beskrivning |
|---------|-------|-------------| |---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial decision model with six layers, evidence-backed decisions, explainability, confidence model, validation scenarios | | 1.0 | 2026-07-02 | Initial decision model with six layers, evidence-backed decisions, explainability, confidence model, validation scenarios, ontology |
--- ---
## STATUS ## STATUS
**DRAFT — Awaiting validation against three scenarios** **DRAFT — Awaiting empirical validation**
- 7 scenarios prepared
- Decision Invariance Test defined
- Evidence Variation Test defined
- Decision Quality Gate defined
- Ontology defined
**Next:** Validate against real data before freezing
docs/design/DECISION_PIPELINE_v1.0.md
+269
View File
@@ -0,0 +1,269 @@
# DECISION PIPELINE v1.0
**Transformation Chain from Reality to Decision**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | DRAFT |
| **Scope** | All Landvex data flows, from collection to decision |
---
## The Pipeline
```
Reality
↓
Observation
↓
Evidence
↓
Finding
↓
Decision
↓
Action
↓
Business Impact
```
---
## Step 1: Observation
| | |
|---|---|
| **Input** | Photo, video, GPS, timestamp, sensor data |
| **Transformation** | AI detects objects, classifies, measures |
| **Output** | Observation (typed, located, timed) |
| **Owner** | Detection Engine |
**Example:**
```
Input: Mobile photo of road + GPS coordinates
Transformation: AI identifies crack, measures 15cm width
Output: Observation {type: "crack", size: "15cm", location: [lat, lng]}
```
---
## Step 2: Evidence
| | |
|---|---|
| **Input** | Observations, history, GIS, weather, traffic |
| **Transformation** | Correlation, deduplication, context enrichment |
| **Output** | Evidence Bundle (linked observations with context) |
| **Owner** | Evidence Engine |
**Example:**
```
Input: 3 crack observations + road age + traffic volume
Transformation: Correlate by location, check against historical data
Output: Evidence {observations: [obs1, obs2, obs3], trend: "increasing", confidence: 0.91}
```
---
## Step 3: Finding
| | |
|---|---|
| **Input** | Evidence Bundle |
| **Transformation** | Rules, thresholds, AI reasoning, pattern matching |
| **Output** | Finding (pattern, conclusion, severity) |
| **Owner** | Analysis Engine |
**Example:**
```
Input: Evidence Bundle (3 cracks, trend increasing)
Transformation: Compare against degradation models, calculate severity score
Output: Finding {description: "Road degraded 15%", severity: "high", confidence: 0.87}
```
---
## Step 4: Decision
| | |
|---|---|
| **Input** | Finding + business rules + priorities + constraints |
| **Transformation** | Recommendation generation, priority scoring, action mapping |
| **Output** | Decision (recommended action, urgency, rationale) |
| **Owner** | Decision Engine |
**Example:**
```
Input: Finding (road degraded 15%) + maintenance schedule + budget constraints
Transformation: Generate recommendation, calculate urgency, map to action
Output: Decision {action: "inspect", urgency: "14 days", rationale: "Safety risk"}
```
---
## Step 5: Action
| | |
|---|---|
| **Input** | Decision + user confirmation + resources |
| **Transformation** | Task creation, scheduling, assignment, tracking |
| **Output** | Action (scheduled, assigned, tracked) |
| **Owner** | Action Engine |
**Example:**
```
Input: Decision (inspect in 14 days) + user approval + inspector availability
Transformation: Create work order, schedule inspection, assign team
Output: Action {task_id: "WO-2026-001", scheduled: "2026-07-16", assigned: "Team A"}
```
---
## Step 6: Business Impact
| | |
|---|---|
| **Input** | Action completion + before/after measurements + costs |
| **Transformation** | Impact calculation, ROI analysis, risk reduction quantification |
| **Output** | Business Impact (measurable effect) |
| **Owner** | Impact Engine |
**Example:**
```
Input: Inspection completed + new measurements + actual costs
Transformation: Compare before/after, calculate risk reduction, quantify savings
Output: Business Impact {risk_reduced: "12% → 3%", cost_avoided: "$50,000", time_saved: "2 weeks"}
```
---
## Step 7: Learning
| | |
|---|---|
| **Input** | Business Impact + original Decision Object + actual outcomes |
| **Transformation** | Compare prediction vs reality, adjust models and rules |
| **Output** | Improved models, updated thresholds, better recommendations |
| **Owner** | Learning Engine |
**Example:**
```
Input: Business Impact + original Decision {confidence: 0.87, action: "inspect"}
Transformation: Was recommendation followed? Did it produce desired effect? Was confidence correct?
Output: Learning {model_adjustment: "increase crack threshold by 5%", confidence_calibration: "0.87 → 0.92"}
```
**Learning questions:**
- Was the recommendation executed?
- Did it produce the desired effect?
- Was the confidence correct?
- Was the recommendation too aggressive or too cautious?
- Do rules or models need adjustment?
---
## Control Intelligence
**LandveX produces Control Intelligence, not AI analysis.**
Control Intelligence consists of:
- Observations
- Evidence
- Findings
- Recommendations
- Business Impact
- Learning
**Not:** "AI analyzes the video"
**But:** "LandveX produces a recommendation to inspect Road A12 within 14 days"
AI is implementation. Control Intelligence is the product.
---
## Architecture Layers
```
┌─────────────────────────────────────┐
│ Presentation Layer │
│ Dashboard, API, Reports │
├─────────────────────────────────────┤
│ Decision Layer │
│ Recommendations, Priorities │
├─────────────────────────────────────┤
│ Intelligence Layer │
│ Findings, Analysis │
├─────────────────────────────────────┤
│ Knowledge Layer │
│ Observations, Evidence, History │
├─────────────────────────────────────┤
│ Reality Layer │
│ Collection, Sensors, Mobile │
└─────────────────────────────────────┘
```
| Layer | Components | Responsibility |
|-------|-----------|----------------|
| **Reality** | quiXzoom app, drones, sensors, cameras | Collect raw data |
| **Knowledge** | Detection Engine, Evidence Engine | Structure and enrich |
| **Intelligence** | Analysis Engine | Find patterns |
| **Decision** | Decision Engine | Generate recommendations |
| **Presentation** | Dashboard, API, Reports | Show decisions |
**Plus Learning Loop:** Business Impact feeds back to Intelligence Layer to improve future recommendations.
---
## Communication Principle
**Not:**
```
Video → AI → Score
```
**But:**
```
Observation → Analysis → Recommendation
```
AI is implementation. Recommendation is the product.
---
## Target Customer Cases
Three customer types to validate the pipeline:
| Customer Type | Decision | Why Important |
|---------------|----------|---------------|
| **Municipality** | "Inspect or wait?" | Maintenance and prioritization |
| **Property Owner** | "Repair now or plan later?" | Cost vs risk |
| **Contractor/Operations** | "Which action first?" | Operational planning |
**Goal:** Same Decision Pipeline works for three different customer types, not just three technical scenarios.
## Validation Requirements
Before freezing Decision Pipeline v1.0:
1. **Three real customer cases** — municipalities, property owners, or contractors follow the full chain
2. **Run each case through entire Decision Pipeline** — from observation to business impact to learning
3. **Document where pipeline breaks** — not where you think it might break
4. **Revise only after** — model changes when data contradicts model, not before
5. **Empirical validation** — same Decision Object works for real data
6. **End-to-end test** — from observation to business impact
---
## ändringshistoria
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial decision pipeline with 6 steps, 5 layers, validation requirements |
---
## STATUS
**DRAFT — Awaiting empirical validation with real customer cases**