boc/docs/design/EPIC-001-First-Verified-Decision.md

EPIC-001: First Verified Decision

Goal: Prove the Intelligence Lab works end-to-end with real data

Epic	001
Status	READY FOR DEVELOPMENT
Goal	A pilot can film a real object, upload, get a Decision Case, review AI, correct annotations, see the evidence chain, approve the case, with full version control and traceability
Success	Complete vertical slice from reality to verified decision

---

STOP Rule

No new pipeline may be implemented until at least 20 real Decision Cases have been produced through the existing pipeline.

Observe first, improve later.

---

Field Readiness Gate

Before building any new feature, answer:

Question	Must Answer
Can we use this during a real pilot day?	Yes
Will it give us better observation data?	Yes
Will it reduce manual work?	Yes
Will it improve Decision Cases?	Yes
Will it help us validate the model?	Yes

If no on most questions — the feature waits.

---

Vertical User Journey (Demo)

The complete journey that can be demonstrated in minutes:

quiXzoom
↓
Take photo or video
↓
Mission Import
↓
Raw Dataset saved
↓
Dataset Explorer shows mission
↓
AI creates Observation
↓
User corrects if needed
↓
Decision Case created
↓
Decision Viewer shows:
  Observation
  ↓
  Evidence
  ↓
  Finding
  ↓
  Decision
  ↓
  Business Impact

If this journey works, the core is proven.

Sprint Goal

Every sprint must result in more verified Decision Cases from real pilot missions.

Keep development close to user reality. Intelligence Lab grows from actual needs, not assumptions.

---

Stories

Story 1: Mission Import

As a field engineer
I want to upload mission data
So that raw data is stored immutably

Video + Images + GPS + EXIF
↓
Raw Dataset (immutable, versioned)

Acceptance:

• Upload video and images
• Extract and display GPS, timestamp, device metadata
• Store raw data with checksum
• Show upload progress and confirmation

Why first: Proves we can receive real data.

---

Story 2: Dataset Explorer

As a field engineer
I want to browse and search missions
So that I can find specific observations

Features:

• List view
• Map view
• Filter by date, location, type
• Search by metadata
• Open mission to see details

Acceptance:

• Browse all missions
• Filter by date range
• Filter by location
• Search by metadata
• Open mission detail view

Why second: Makes data visible and searchable.

---

Story 3: Annotation Workspace

As a field engineer
I want to review and correct AI suggestions
So that observations are accurate

Image
↓
AI Detection (bounding box + label + confidence)
↓
Human Review (correct / modify / reject)
↓
Version History

Acceptance:

• Show image with AI bounding boxes
• Display AI label and confidence
• Allow correction of label
• Allow adjustment of bounding box
• Allow rejection of detection
• Save version history
• Show before/after comparison

Why third: First human-in-the-loop.

---

Story 4: Decision Case

As a field engineer
I want to see the full decision chain
So that I understand why a decision was recommended

Observation
↓
Evidence
↓
Finding
↓
Decision
↓
Business Impact

Acceptance:

• Display observation with image/video
• Show evidence (linked observations)
• Show finding (pattern/conclusion)
• Show decision (recommended action)
• Show business impact (risk, cost, time)
• Allow approval or rejection
• Show explainability chain (clickable)

Why fourth: First verified decision.

---

Story 5: Replay

As a field engineer
I want to replay a mission
So that I can review the entire chain

V1: Simple playback — step through the chain
Not in V1: AI comparison, model versioning

Mission-001
↓
Step 1: Observation
Step 2: Evidence
Step 3: Finding
Step 4: Decision
Step 5: Business Impact

Acceptance:

• Select mission to replay
• Step through each stage
• Show data at each stage
• Navigate forward and backward

Why fifth: Proves the chain is reproducible.

---

Story 6: Session Management

As a field engineer
I want to create and manage field sessions
So that missions are organized by location and date

Field Session
├── Location: Huddinge
├── Date: 2026-08-14
└── Missions: [Mission-001, Mission-002, ...]

Acceptance:

• Create session with location and date
• List all sessions
• Open session to see missions

Why last: Organizational layer on top of working core.

---

Golden Mission

A real mission that never changes, used as regression test.

Golden Mission 001
├── Location: Huddinge
├── Images: 52
├── Videos: 4
├── Observations: 31
└── Verified Decision Cases: 8

Every new model runs against the same mission. See immediately if something got better or worse.

Review (First-Class Object)

Not just Annotation. Full quality flow:

Observation
↓
AI
↓
Human Review
↓
Approved / Rejected / Needs More Evidence

Makes the entire quality flow traceable.

Dashboard v1

Extremely simple:

FIELD STATUS

Sessions:        3
Missions:        27
Decision Cases:  11
Pending Reviews: 6
Verified Decisions: 8

[Continue Reviewing]

Should feel like a work tool, not a BI system.

Not in First Release

Intentionally postponed:

Feature	Why Postponed
GPU Queue	Not needed for 20 Decision Cases
Hyperparameter Search	Not needed for validation
Distributed Training	Not needed for MVP
Benchmark (15 models)	Not needed for first cases
Canary Deployment	Not needed for internal tool
Auto Retraining	Not needed until model validated
Bias Dashboard	Not needed until diverse data
Drift Detection	Not needed until production

These are important but don't help reach the first verified workflow.

---

Definition of "First Verified Decision"

A First Verified Decision is a Decision Case that:

• Is built on real observation data
• Has been reviewed by a human
• Has a complete evidence chain
• Is fully reproducible from raw data to recommendation

Definition of Done (Epic)

• A pilot can film a real object in quiXzoom
• Upload material to Intelligence Lab
• Get a Decision Case created automatically
• Review AI results
• Correct annotations
• See full evidence chain
• Approve Decision Case
• Everything saved versioned and traceable
• At least 1 real Decision Case produced
• Meets "First Verified Decision" definition

---

Definition of Ready (Next Epic)

Epic-002 can start when:

• 20 real Decision Cases exist
• Field Readiness Gate passed
• STOP rule satisfied

---

Technical Stack (Recommended)

Layer	Technology	Rationale
Frontend	React + TypeScript (strict)	Type safety, component ecosystem
Backend	Node.js + Express + TypeScript	Same language, fast development
Database	PostgreSQL	ACID, JSON support, proven
Storage	S3/R2	Immutable object storage
Queue	Bull (Redis)	Proven, observable job queue
AI	Python microservice	Model inference separate from API
Git	All code versioned	Traceability

---

Quality Gates

Gate	Requirement
Code	TypeScript strict, ≥80% test coverage
Security	No secrets in code, OAuth 2.0
Audit	All actions logged, immutable
Deploy	GitOps, reproducible builds

---

ändringshistoria

Version	Datum	Beskrivning
1.0	2026-07-02	Initial Epic-001 specification
1.1	2026-07-02	Reordered stories (Mission Import first, Session Management last), added Golden Mission, Review object, Dashboard v1, vertical user journey, First Verified Decision definition

---

STATUS

READY FOR DEVELOPMENT