From c47a58f76be2206713ed3f6178c7bbfe31af12dd Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 13:34:05 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20Epic-001=20=E2=80=94=20First=20Verified?= =?UTF-8?q?=20Decision=20specification?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- .../EPIC-001-First-Verified-Decision.md | 270 ++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 docs/design/EPIC-001-First-Verified-Decision.md diff --git a/docs/design/EPIC-001-First-Verified-Decision.md b/docs/design/EPIC-001-First-Verified-Decision.md new file mode 100644 index 000000000..4f0b9d274 --- /dev/null +++ b/docs/design/EPIC-001-First-Verified-Decision.md @@ -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**