docs: Epic-001 — First Verified Decision specification

- STOP Rule: No new pipeline until 20 real Decision Cases exist - Field Readiness Gate: 5 questions before building any feature - Sprint Goal: Every sprint must produce more verified Decision Cases - Six stories: 1. Session Management — organize missions by location/date 2. Mission Import — upload video/images/GPS/EXIF, store immutably 3. Dataset Explorer — browse, filter, search, map view 4. Annotation Workspace — review/correct AI, version history 5. Decision Case — full chain: Observation→Evidence→Finding→Decision→Business Impact 6. Replay — step through mission chain (V1: simple playback) - Not in first release (intentionally postponed): GPU Queue, Hyperparameter Search, Distributed Training, Benchmark, Canary Deployment, Auto Retraining, Bias Dashboard, Drift Detection - Definition of Done: Complete vertical slice from reality to verified decision - Definition of Ready for Epic-002: 20 real Decision Cases + Field Readiness Gate - Technical stack: React+TypeScript, Node.js+Express, PostgreSQL, S3/R2, Bull, Python AI service - Quality gates: TypeScript strict ≥80% coverage, no secrets, OAuth 2.0, immutable audit log, GitOps Rationale: Prove the system works end-to-end before scaling. Focus on learning from reality, not building everything upfront.
2026-07-02 13:34:05 +00:00
parent 67ca05f2b2
commit c47a58f76b
1 changed files with 270 additions and 0 deletions
@@ -0,0 +1,270 @@
+# 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.
+
+---
+
+## 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: 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
+
+---
+
+### Story 2: 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
+
+---
+
+### Story 3: 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
+
+---
+
+### Story 4: 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
+
+---
+
+### Story 5: 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)
+
+---
+
+### Story 6: 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
+
+---
+
+## 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 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
+
+---
+
+## 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 |
+
+---
+
+## STATUS
+
+**READY FOR DEVELOPMENT**