From b4391f96007dfc5138d0c40a357bfbd9bec73bf2 Mon Sep 17 00:00:00 2001
From: Bernt <bernt@aamos.systems>
Date: Thu, 2 Jul 2026 13:50:38 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20PR-001=20Domain=20Model=20v1.1=20?=
 =?UTF-8?q?=E2=80=94=20Human=20Intelligence=20as=20future=20module?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Added Human Intelligence as separate external module (not in core domain)
- Positioning: External Intelligence Module, not part of Epic-001
- Architecture: Reality Intelligence with four branches:
  - Infrastructure Intelligence (core, Epic-001)
  - Operational Intelligence (future)
  - Human Intelligence (future module)
  - External Intelligence (future)

- Human Insight Artifact: Source, Geography, Period, Metrics, Confidence
- Usage: Linked to Area or Decision Case, never mixed with raw observations
- Example: Decision Case enriched with 'Many complaints last 30 days'
- When: After Epic-001 stable and 20+ Decision Cases exist

Rationale: Keep core domain clean. Human data is context, not observation.
Add after basic pipeline is proven.
---
 docs/design/PR-001-DOMAIN-MODEL.md | 54 ++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/docs/design/PR-001-DOMAIN-MODEL.md b/docs/design/PR-001-DOMAIN-MODEL.md
index d1f25dfc9..2d6bb8bb2 100644
--- a/docs/design/PR-001-DOMAIN-MODEL.md
+++ b/docs/design/PR-001-DOMAIN-MODEL.md
@@ -521,6 +521,60 @@ The concepts `Session`, `Mission`, `Artifact`, `Observation`, `Evidence`, `Findi
 | HTTP endpoints | API concern |
 | Bucket code | Infrastructure concern |
 | AI logic | Separate concern |
+| Human Intelligence | Separate module, not core domain |
+
+---
+
+## Future Module: Human Intelligence (Not in Epic-001)
+
+**Positioning:** External Intelligence Module, not part of core domain.
+
+**Why separate:** Customer satisfaction data is not an observation from reality like a road crack. It is **context** that can influence priorities and decisions.
+
+**Architecture:**
+```
+Reality Intelligence
+│
+├── Infrastructure Intelligence  ← Core (Epic-001)
+│   Roads, Buildings, Parks, Signs
+│
+├── Operational Intelligence     ← Future
+│   SLA, Tickets, Costs, Times
+│
+├── Human Intelligence           ← Future module
+│   Customer satisfaction
+│   Citizen surveys
+│   NPS, Complaints, Feedback
+│
+└── External Intelligence        ← Future
+│   Weather, Traffic, Demographics
+```
+
+**Human Insight Artifact:**
+```
+Human Insight
+├── Source: "Kommunenkät 2026"
+├── Geography: [Stockholm, Nacka]
+├── Period: "Q2 2026"
+├── Metrics:
+│   ├── CSAT: 4.2
+│   ├── NPS: 62
+│   └── Complaint Index: 0.34
+└── Confidence: 0.83
+```
+
+**Usage:** Linked to Area or Decision Case, but never mixed with raw field observations.
+
+**Decision Case with Human Intelligence:**
+```
+Observation: "Crack on main street"
+Evidence: [Image, Video, History, GIS]
+Human Intelligence: "Many complaints last 30 days, low satisfaction index"
+Decision: "Prioritize repair within 14 days"
+Business Impact: "Reduced risk, lower future cost, improved citizen satisfaction"
+```
+
+**When:** After Epic-001 is stable and 20+ Decision Cases exist.
 
 ---