docs(cortex): add PRD, TO and rename swift → cortex
New documents: - prd-cortex-v2.md: Product Requirements Document with MVP scope, user flows, success criteria, and roadmap - to-cortex-v2.md: Technical Design with three-layer architecture, API design, error handling, and logging Renamed files (swift → cortex): - architecture-swift-cortex-v2.md → architecture-cortex-v2.md - fo-swift-intent-system-v2.md → fo-cortex-intent-system-v2.md - haalbaarheidsanalyse-swift-cortex-v2.md → haalbaarheidsanalyse-cortex-v2.md - review-swift-cortex-v2.md → review-cortex-v2.md Updated content: - All swift references replaced with cortex - FO: confidence threshold 0.9 → 0.7 (industry standard) - TO v1.1: Added error handling, input sanitization, improved suïcidaliteit regex, model version note - Legacy docs: Added note about swift → cortex rename 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
colinislit
306
docs/intent/prd-cortex-v2.md
Normal file
306
docs/intent/prd-cortex-v2.md
Normal file
@@ -0,0 +1,306 @@
|
||||
# Product Requirements Document (PRD) – Cortex V2
|
||||
|
||||
**Projectnaam:** Cortex Intent System V2
|
||||
**Versie:** v1.0
|
||||
**Datum:** 30-12-2025
|
||||
**Auteur:** Colin Lit (Antigravity AI)
|
||||
|
||||
---
|
||||
|
||||
## 1. Doelstelling
|
||||
|
||||
**Waarom bouwen we dit?**
|
||||
|
||||
Het huidige Cortex systeem (V1) is **reactief**: de gebruiker geeft een commando, het systeem voert uit. Hoewel dit snel werkt (<100ms), mist het de intelligentie die zorgprofessionals nodig hebben. V2 transformeert Cortex van een "spraakgestuurd toetsenbord" naar een **AI Collega**.
|
||||
|
||||
**Beoogd resultaat:**
|
||||
> Een werkend prototype dat de kernwaarde van "Agency" demonstreert: het systeem begrijpt **meerdere intenties** in één zin, is **context-aware** (snapt wie "hij" is en wat "morgen" betekent), en geeft **proactieve suggesties** op basis van medische logica.
|
||||
|
||||
**Type release:** MVP / Public Prototype ("Build in Public")
|
||||
|
||||
**Kernprincipe:**
|
||||
> "We stoppen met optimaliseren voor milliseconden en starten met optimaliseren voor intelligentie."
|
||||
|
||||
---
|
||||
|
||||
## 2. Doelgroep
|
||||
|
||||
### Primaire gebruikers
|
||||
|
||||
| Rol | Behoeften | Pijnpunten V1 |
|
||||
|-----|-----------|---------------|
|
||||
| **Verpleegkundige** | Snelheid, handen-vrij werken, administratieve lastenverlichting | "Ik moet drie losse commando's geven voor één situatie" |
|
||||
| **Psycholoog** | Nuance, cliënt-context, emotionele lading | "Het systeem snapt niet dat 'uitzichtloos' een alarmsignaal is" |
|
||||
| **Psychiater/Regiebehandelaar** | Veiligheid, medicatie-checks, overzicht | "Ik wil dat het systeem meedenkt over labwaardes en interacties" |
|
||||
|
||||
### Stakeholders
|
||||
|
||||
- **Product Owner:** Waarde aantonen, haalbaarheid bewaken
|
||||
- **Developers:** Technische implementatie, AI-integratie
|
||||
- **UX Designer:** "Invisible Interface" - minder frictie, meer begrip
|
||||
|
||||
### Gebruikersquote (uit UX simulatie)
|
||||
|
||||
> **Regiebehandelaar:** "'Ontlasten' betekent dat ik mijn *intentie* uitspreek, niet mijn *administratie*. Mijn intentie is 'Zorg voor Jan regelen'. De administratie (agenda, brief, notitie) is jullie probleem."
|
||||
|
||||
---
|
||||
|
||||
## 3. Kernfunctionaliteiten (MVP-scope)
|
||||
|
||||
### 3.1 The Three-Layer Cortex Model
|
||||
|
||||
| Layer | Functie | Latency | Voorbeeld |
|
||||
|-------|---------|---------|-----------|
|
||||
| **Layer 1: Reflex Arc** | Lokale regex voor simpele commando's | <20ms | "Agenda vandaag", "Zoek Jan" |
|
||||
| **Layer 2: Intent Orchestrator** | AI-classificatie voor complexe/multi-intent zinnen | ~400ms | "Zeg Jan af en maak notitie: grieperig" |
|
||||
| **Layer 3: Nudge Engine** | Proactieve suggesties na acties | async | "Wondcontrole inplannen over 3 dagen?" |
|
||||
|
||||
### 3.2 MVP Features
|
||||
|
||||
1. **Hybrid Architecture**
|
||||
- Naadloze switch tussen Reflex (lokaal) en Orchestrator (AI)
|
||||
- Confidence threshold: >= 0.7 voor lokale afhandeling
|
||||
- Ambiguity detection: escaleer bij top-2 score delta < 0.1
|
||||
|
||||
2. **Multi-Intent Support**
|
||||
- Herkenning van signaalwoorden: "en", "daarna", "ook", "eerst"
|
||||
- Opsplitsen in Action Chain met sequentiële uitvoering
|
||||
- UI: Stacked Cards met progressie-indicatie
|
||||
|
||||
3. **Context Awareness**
|
||||
- Pronoun resolution: "hij/zij" → actieve patiënt
|
||||
- Relatieve tijd: "morgen", "volgende week" → concrete datum
|
||||
- Context injection: ActivePatient, CurrentView, AgendaToday, RecentIntents
|
||||
|
||||
4. **UI Feedback**
|
||||
- Processing indicator bij AI-acties
|
||||
- ActionChainCard voor meerdere acties
|
||||
- ClarificationCard bij ambigue input
|
||||
|
||||
5. **Basic Nudge (Proof of Concept)**
|
||||
- Hardcoded protocol: Wondzorg → Wondcontrole suggestie
|
||||
- NudgeToast met accept/dismiss en countdown timer
|
||||
|
||||
### 3.3 Ondersteunde Intents
|
||||
|
||||
| Intent | Beschrijving | Layer |
|
||||
|--------|--------------|-------|
|
||||
| `dagnotitie` | Notitie/rapportage maken | Reflex + Orchestrator |
|
||||
| `zoeken` | Patiënt zoeken | Reflex |
|
||||
| `agenda_query` | Agenda bekijken | Reflex |
|
||||
| `overdracht` | Dienst overdracht | Reflex |
|
||||
| `create_appointment` | Afspraak maken | Orchestrator |
|
||||
| `cancel_appointment` | Afspraak annuleren | Orchestrator |
|
||||
| `reschedule_appointment` | Afspraak verzetten | Orchestrator |
|
||||
|
||||
---
|
||||
|
||||
## 4. Gebruikersflows (MVP-flows)
|
||||
|
||||
### Flow 1: Multi-Intent Commando
|
||||
|
||||
```
|
||||
Gebruiker: "Zeg Jan af voor vandaag en maak notitie: hij heeft griep"
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Layer 1 (Reflex): Detecteert "en" → Escaleer │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Layer 2 (Orchestrator): Parse naar 2 acties │
|
||||
│ 1. cancel_appointment (Jan, vandaag) │
|
||||
│ 2. dagnotitie (Jan, "hij heeft griep") │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ UI: ActionChainCard │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ ✅ 1. Afspraak Jan geannuleerd │ │
|
||||
│ ├─────────────────────────────────────┤ │
|
||||
│ │ ⏳ 2. Notitie: "hij heeft griep" │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Flow 2: Context-Aware Pronoun Resolution
|
||||
|
||||
```
|
||||
Context: Patiënt "Marie de Vries" is geopend in dossier
|
||||
|
||||
Gebruiker: "Maak notitie voor haar: medicatie ingenomen"
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Layer 2: Resolves "haar" → Marie de Vries │
|
||||
│ patientResolution: "pronoun" │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
Notitie aangemaakt voor Marie de Vries
|
||||
```
|
||||
|
||||
### Flow 3: Proactieve Suggestie (Nudge)
|
||||
|
||||
```
|
||||
Gebruiker: "Notitie: wond verzorgd, ziet er goed uit"
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Notitie opgeslagen ✅ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Layer 3 (Nudge): Protocol "wondzorg-controle" match │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ NudgeToast (bottom-right) │
|
||||
│ 💡 "Wondcontrole inplannen over 3 dagen?" │
|
||||
│ [Ja, doe maar] [Nee, bedankt] │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Flow 4: Simpel Commando (Reflex)
|
||||
|
||||
```
|
||||
Gebruiker: "Agenda vandaag"
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Layer 1 (Reflex): Match "agenda" pattern │
|
||||
│ Confidence: 1.0 → Direct uitvoeren │
|
||||
│ Latency: <20ms │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
Agenda artifact opent direct (geen spinner)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Niet in Scope
|
||||
|
||||
De volgende features vallen **bewust buiten** de MVP:
|
||||
|
||||
| Feature | Reden | Post-MVP? |
|
||||
|---------|-------|-----------|
|
||||
| **Complete medische protocollen** | Te complex voor prototype | Ja, rule-engine |
|
||||
| **Rollback/Undo** | Vereist transactie-systeem | Ja |
|
||||
| **Offline mode** | Prototype veronderstelt internet | Nee (low priority) |
|
||||
| **Advanced error handling** | Retry-mechanismes, circuit breakers | Ja |
|
||||
| **Analytics & learning** | Telemetry opslag, model training | Ja |
|
||||
| **Productie-beveiliging** | NEN7510 compliance, audit logs | Ja (kritiek voor productie) |
|
||||
| **Externe integraties** | Teams, ECD-koppelingen | Ja |
|
||||
| **Adaptive confidence** | User-specific thresholds | Nice-to-have |
|
||||
| **Sentiment analysis** | Emotionele lading detectie | Nice-to-have |
|
||||
|
||||
---
|
||||
|
||||
## 6. Succescriteria
|
||||
|
||||
### Functionele criteria
|
||||
|
||||
| Criterium | Target | Meetmethode |
|
||||
|-----------|--------|-------------|
|
||||
| Multi-intent herkenning | "X en Y" zinnen correct gesplitst | Test dataset (50+ zinnen) |
|
||||
| Pronoun resolution | "hij/zij/hem/haar" correct resolved | Test met actieve patiënt context |
|
||||
| Reflex hit rate | >70% lokaal afgehandeld | Logging metrics |
|
||||
| AI latency p95 | <800ms | Performance monitoring |
|
||||
| Nudge trigger | Wondzorg → suggestie getoond | Manual test |
|
||||
|
||||
### UX criteria
|
||||
|
||||
| Criterium | Target |
|
||||
|-----------|--------|
|
||||
| Geen "Ik begrijp het niet" | Altijd een poging tot begrip, eventueel met clarification |
|
||||
| Processing feedback | Spinner bij AI-acties, geen "bevroren" scherm |
|
||||
| Demo duur | Volledige flow demonstreerbaar in ≤5 minuten |
|
||||
|
||||
### Technische criteria
|
||||
|
||||
| Criterium | Target |
|
||||
|-----------|--------|
|
||||
| Reflex latency | <20ms |
|
||||
| AI fallback werkt | Bij Anthropic 503 → graceful degradation naar Reflex |
|
||||
| Geen PII in logs | Input gesanitized voor productie logging |
|
||||
|
||||
---
|
||||
|
||||
## 7. Risico's & Mitigatie
|
||||
|
||||
| Risico | Impact | Kans | Mitigatie |
|
||||
|--------|--------|------|-----------|
|
||||
| **AI output inconsistent** | Hoog | Middel | Strikte JSON schema, temperature=0, fallback to unknown |
|
||||
| **Multi-intent parsing faalt** | Hoog | Laag | Uitgebreide test dataset, fallback naar single intent |
|
||||
| **Scope creep** | Middel | Hoog | Strikte MVP scope, 6 user stories max |
|
||||
| **Privacy breach (logs)** | Hoog | Laag | Input sanitization, geen PII in production logs |
|
||||
| **Anthropic API down** | Middel | Laag | Graceful degradation naar Reflex-only mode |
|
||||
| **Performance degradatie** | Middel | Laag | Caching, monitoring, threshold tuning |
|
||||
| **False positive Nudge** | Laag | Middel | Specifieke regex, word boundaries, test edge cases |
|
||||
|
||||
---
|
||||
|
||||
## 8. Roadmap / Vervolg (Post-MVP)
|
||||
|
||||
### Fase 1: MVP (Nu)
|
||||
- Hybrid architecture (Reflex + Orchestrator)
|
||||
- Multi-intent support
|
||||
- Context awareness
|
||||
- Basic Nudge (wondzorg)
|
||||
|
||||
### Fase 2: Enhanced Nudge (Post-MVP)
|
||||
- Meerdere protocol rules (medicatie, crisis)
|
||||
- Admin UI voor rule management
|
||||
- NLP/AI voor complexere matching
|
||||
|
||||
### Fase 3: Productie-ready
|
||||
- NEN7510 compliance
|
||||
- Audit logging
|
||||
- Advanced error handling (retry, circuit breaker)
|
||||
- Rollback support
|
||||
|
||||
### Fase 4: Intelligence
|
||||
- Adaptive confidence (user-specific thresholds)
|
||||
- Sentiment analysis
|
||||
- Learning from corrections
|
||||
- Predictive suggestions
|
||||
|
||||
### Fase 5: Integraties
|
||||
- ECD-koppelingen (PinkRoccade, Nedap)
|
||||
- Teams/Slack integratie
|
||||
- Voice-first mobile app
|
||||
|
||||
---
|
||||
|
||||
## 9. Bijlagen & Referenties
|
||||
|
||||
### Gerelateerde documenten
|
||||
|
||||
| Document | Locatie | Beschrijving |
|
||||
|----------|---------|--------------|
|
||||
| FO Cortex V2 | `docs/intent/fo-cortex-intent-system-v2.md` | Functioneel ontwerp |
|
||||
| TO Cortex V2 | `docs/intent/to-cortex-v2.md` | Technisch ontwerp |
|
||||
| Architectuur V2 | `docs/intent/architecture-cortex-v2.md` | Uitgebreid architectuurplan |
|
||||
| Haalbaarheidsanalyse | `docs/intent/haalbaarheidsanalyse-cortex-v2.md` | Gap analyse en effort schatting |
|
||||
| MVP User Stories | `docs/intent/mvp-userstories-intent-system.md` | User stories en acceptatiecriteria |
|
||||
| UX Evaluatie | `docs/intent/ux-evaluation-intent-scalability.md` | UX perspectief op architectuur |
|
||||
| UX Simulatie | `docs/intent/ux-simulation-intent-next-level.md` | Brainstorm "Next Level" features |
|
||||
|
||||
### Tech stack
|
||||
|
||||
- **Frontend:** Next.js 15, React, TailwindCSS, shadcn/ui
|
||||
- **State:** Zustand
|
||||
- **Backend:** Next.js API Routes
|
||||
- **Database:** Supabase (PostgreSQL)
|
||||
- **AI:** Claude 3.5 Haiku (Anthropic)
|
||||
|
||||
### Versie historie
|
||||
|
||||
| Versie | Datum | Auteur | Wijzigingen |
|
||||
|--------|-------|--------|-------------|
|
||||
| 1.0 | 30-12-2025 | Colin Lit | Initieel document |
|
||||
Reference in New Issue
Block a user