From f05fded74effd33372296db4452937d1247c16ee Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 12:13:25 +0000 Subject: [PATCH] docs: Decision Pipeline v1.0 + Learning Loop + Control Intelligence + 3 Customer Cases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- docs/design/DECISION_MODEL_REVIEW.md | 217 +++++++++++++++++++++ docs/design/DECISION_MODEL_v1.0.md | 158 +++++++++++++-- docs/design/DECISION_PIPELINE_v1.0.md | 269 ++++++++++++++++++++++++++ 3 files changed, 627 insertions(+), 17 deletions(-) create mode 100644 docs/design/DECISION_MODEL_REVIEW.md create mode 100644 docs/design/DECISION_PIPELINE_v1.0.md diff --git a/docs/design/DECISION_MODEL_REVIEW.md b/docs/design/DECISION_MODEL_REVIEW.md new file mode 100644 index 000000000..b9d45b567 --- /dev/null +++ b/docs/design/DECISION_MODEL_REVIEW.md @@ -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** diff --git a/docs/design/DECISION_MODEL_v1.0.md b/docs/design/DECISION_MODEL_v1.0.md index 7e8600c3d..8e38e5184 100644 --- a/docs/design/DECISION_MODEL_v1.0.md +++ b/docs/design/DECISION_MODEL_v1.0.md @@ -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 **Input sources:** @@ -291,6 +348,21 @@ Before freezing Decision Model v1.0, validate against diverse scenarios: **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 @@ -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 **Decision Model v1.0 is validated when:** -1. All 7 scenarios produce valid Decision Objects -2. Decision Invariance Test passes -3. Evidence Variation Test passes -4. Decision Quality Gate passes for all scenarios -5. "No action" scenario works correctly +1. All 8 scenarios produce valid Decision Objects +2. Manual review passes for all scenarios +3. Decision Invariance Test passes +4. Evidence Variation Test passes +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 @@ -351,30 +454,51 @@ Before displaying any decision to the user: ## Relationship to Dashboard **Dashboard is not:** 120 widgets -**Dashboard is:** Decision Card visualization +**Dashboard is:** Object visualization with decisions ``` -Area Score - ↓ -Top 3 Decisions - ↓ -Map - ↓ -Evidence - ↓ -History +────────────────────────── +AREA SCORE +83 +↑ +4 +────────────────────────── +TOP DECISIONS +Inspect Road A12 [High] +Repair Drain B [Medium] +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 | 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 -**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 diff --git a/docs/design/DECISION_PIPELINE_v1.0.md b/docs/design/DECISION_PIPELINE_v1.0.md new file mode 100644 index 000000000..30b8367e2 --- /dev/null +++ b/docs/design/DECISION_PIPELINE_v1.0.md @@ -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**