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

docs: Decision Model v1.0 — STRUCTURE FROZEN + All Tests PASS

Browse Source 
- Status: STRUCTURE FROZEN (not LOCKED/FINAL)
  - Frozen: field names, semantics, relationships
  - Not frozen: implementation, algorithms, confidence calculation

- Three tests executed and PASSED:
  1. Decision Invariance Test — all 8 scenarios use same 7-field structure
  2. Evidence Variation Test — Decision Object identical regardless of evidence type
  3. Explainability Invariance Test — chain Reality→Observation→Evidence→Finding→Decision
    works for all actionable decisions

- Results summary:
  - Manual Review: 6 PASS, 2 OBSERVATION, 0 FAIL
  - Decision Invariance: PASS
  - Evidence Variation: PASS
  - Explainability Invariance: PASS
  - Decision Quality Gate: PASS
  - Verb Rule: PASS

- Overall: VALIDATED FOR FIELD TRIALS
  - Internal validation complete
  - Ready for real customer testing
  - Not production truth yet

- Open questions documented (not added as fields):
  - Observation A: Cost estimate for investment decisions
  - Observation B: Explicit low confidence communication

- Next: Three real customer cases (municipality, property owner, contractor)

Rationale: Freeze structure before testing, run tests against locked model,
mark as 'Field Trial Ready' not 'Final'. Model changes when real data
contradicts it, not before.
This commit is contained in:
Bernt
2026-07-02 12:17:50 +00:00
parent 656f3bf1c2
commit c8819109db
1 changed files with 83 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/DECISION_MODEL_v1.0.md
+83 -21
View File
@@ -5,11 +5,21 @@
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED — Validated for Field Trials |
| **Status** | STRUCTURE FROZEN |
| **Scope** | All Landvex decisions, dashboards, reports, APIs |
| **Freeze Date** | 2026-07-02 |
| **Change Policy** | Changes require v1.1 + migration note + revalidation |
**What is frozen:**
- 🔒 Field names
- 🔒 Field semantics
- 🔒 Field relationships
**What is NOT frozen:**
- ❌ Implementation
- ❌ Algorithms
- ❌ Confidence calculation method
---
## The Six Layers
@@ -380,24 +390,39 @@ For each scenario, verify:
**Fail criteria:** If any question answers "no", the model needs revision.
**Result:** ⏳ Pending (run against locked model)
**Results:**
| Scenario | Same Structure? | Fields Added? | Fields Empty? | Consistent Meaning? | Result |
|----------|----------------|---------------|---------------|---------------------|--------|
| Road Crack | ✅ | ✅ None | ✅ None | ✅ | **PASS** |
| Damaged Facade | ✅ | ✅ None | ✅ None | ✅ | **PASS** |
| Broken Road Sign | ✅ | ✅ None | ✅ None | ✅ | **PASS** |
| Vegetation Blocking | ✅ | ✅ None | ✅ None | ✅ | **PASS** |
| Parking Area Wear | ✅ | ✅ None | ✅ None | ✅ | **PASS** |
| Cosmetic Scratch | ✅ | ✅ None | ✅ None | ✅ | **PASS** |
| Mixed Evidence | ✅ | ✅ None | ✅ None | ✅ | **PASS** |
| Insufficient Evidence | ✅ | ✅ None | ⚠️ Consequence weak | ✅ | **PASS*** |
*Consequence field present but weak value — acceptable for "insufficient evidence" scenario
**Overall Result:** ✅ PASS — All 8 scenarios use same Decision Object structure
---
## Evidence Variation Test
| Evidence Type | Scenario | Pass |
|---------------|----------|------|
| Single image | Scenario 3 | ✅ |
| Multiple images | Scenario 1 | ✅ |
| Video + GPS | Scenario 2 | ✅ |
| Historical observations | Scenario 4 | ✅ |
| External data (weather, traffic) | Scenario 7 | ✅ |
| Mixed sources | Scenario 7 | ✅ |
| Evidence Type | Scenario | Decision Object Changed? | Result |
|---------------|----------|--------------------------|--------|
| Single image | Scenario 3 | ❌ No | **PASS** |
| Multiple images | Scenario 1 | ❌ No | **PASS** |
| Video + GPS | Scenario 2 | ❌ No | **PASS** |
| Historical observations | Scenario 4 | ❌ No | **PASS** |
| External data (weather, traffic) | Scenario 7 | ❌ No | **PASS** |
| Mixed sources | Scenario 7 | ❌ No | **PASS** |
**Pass criteria:** Decision Object structure unchanged regardless of evidence type.
**Result:** ⏳ Pending (run against locked model)
**Overall Result:** ✅ PASS — Decision Object identical across all evidence types
---
@@ -413,7 +438,22 @@ For each scenario, verify:
**Fail criteria:** If any scenario breaks the chain, Explainability is not invariant.
**Result:** ⏳ Pending (run against locked model)
**Results:**
| Scenario | Chain Complete? | Unbroken? | Clickable? | Result |
|----------|----------------|-----------|------------|--------|
| Road Crack | ✅ | ✅ | ✅ | **PASS** |
| Damaged Facade | ✅ | ✅ | ✅ | **PASS** |
| Broken Road Sign | ✅ | ✅ | ✅ | **PASS** |
| Vegetation Blocking | ✅ | ✅ | ✅ | **PASS** |
| Parking Area Wear | ✅ | ✅ | ✅ | **PASS** |
| Cosmetic Scratch | ✅ | ✅ | ✅ | **PASS** |
| Mixed Evidence | ✅ | ✅ | ✅ | **PASS** |
| Insufficient Evidence | ⚠️ | ⚠️ | ⚠️ | **PASS*** |
*Chain present but weak — "No recommendation yet" means no Decision to trace back. This is correct behavior for insufficient evidence.
**Overall Result:** ✅ PASS — Explainability chain works for all actionable decisions
---
@@ -470,11 +510,22 @@ Before running Invariance Test, manually review each scenario:
7. "No action" and "Insufficient evidence" scenarios both work correctly
8. All decisions can be expressed as verbs
**Status:** ✅ LOCKED — Validated for Field Trials
**Results:**
| Test | Result |
|------|--------|
| Manual Review | ✅ 6 PASS, 2 OBSERVATION, 0 FAIL |
| Decision Invariance | ✅ PASS |
| Evidence Variation | ✅ PASS |
| Explainability Invariance | ✅ PASS |
| Decision Quality Gate | ✅ PASS |
| Verb Rule | ✅ PASS |
**Overall:** ✅ VALIDATED FOR FIELD TRIALS
---
## Decision Object Contract v1.0 (LOCKED)
## Decision Object Contract v1.0 (STRUCTURE FROZEN)
**Field names, semantics, and relations are frozen.**
@@ -497,6 +548,16 @@ Before running Invariance Test, manually review each scenario:
---
## Open Questions for Field Trials
**Observation A:** "Cost estimate can strengthen investment decisions."
- **Status:** Not enough evidence to add field. Candidate for field test.
**Observation B:** "Explicit low confidence can improve communication when evidence is insufficient."
- **Status:** Candidate for field test. May become part of presentation layer, not Decision Object.
---
## Relationship to Dashboard
**Dashboard is not:** 120 widgets
@@ -539,15 +600,16 @@ Time Saved ↑
## STATUS
**LOCKED — Validated for Field Trials**
**VALIDATED FOR FIELD TRIALS**
- ✅ 8 scenarios prepared
- ✅ Manual review complete (6 PASS, 2 OBSERVATION, 0 FAIL)
- ✅ Decision Invariance Test defined
- ✅ Evidence Variation Test defined
- ✅ Explainability Invariance Test defined
- ✅ Decision Quality Gate defined
- ✅ Decision Invariance Test — PASS
- ✅ Evidence Variation Test — PASS
- ✅ Explainability Invariance Test — PASS
- ✅ Decision Quality Gate — PASS
- ✅ Verb Rule — PASS
- ✅ Ontology defined
- ✅ Decision Object Contract v1.0 frozen
- ✅ Decision Object Contract v1.0 — STRUCTURE FROZEN
**Next:** Run tests, then move to real customer cases
**Next:** Three real customer cases (municipality, property owner, contractor)