triqura-ecd/docs/intent/fo-cortex-intent-system-v2.md

🧩 Functioneel Ontwerp (FO) – Cortex Intent System V2

Projectnaam: Cortex Intent Architecture V2 Versie: v2.0 (Draft) Datum: 29-12-2025 Auteur: Colin Lit (Antigravity AI)

---

1. Doel en relatie met het PRD

🎯 Doel van dit document: Dit FO beschrijft de functionele werking van de "Next Gen" Cortex Intent Architectuur. Waar V1 focuste op snelheid en basiscommando's ("Reactive"), focust V2 op contextbegrip, meervoudige intenties en proactieve ondersteuning ("Agentic").

📘 Relatie tot vorige documentatie: Dit document vervangt de architectuur uit architecture-intent-scalability.md (Strategie 1: Strict Hierarchy) en kiest voor de Hybride Route (Strategie 5 + Agentic extensions) zoals besproken in de UX Evaluatie.

---

2. Overzicht van de belangrijkste onderdelen

🎯 Architectuurmodel: "The Cortex" Het systeem bestaat uit drie samenwerkende lagen die elk een andere rol spelen in de interactie:

1. Layer 1: The Reflex Arc (De Snelle Reflex)

   • Rol: Directe uitvoering van simpele, veelvoorkomende commando's.
   • Voorbeeld: "Afspraken vandaag", "Navigeer dossier".

2. Layer 2: The Intent Orchestrator (Het Brein)

   • Rol: AI-gedreven analyse voor complexe zinnen, context-disambiguatie en Multi-Intents.
   • Voorbeeld: "Zeg Jan af en maak een notitie."

3. Layer 3: The Nudge & Suggestion Engine (De Partner)

   • Rol: Proactieve business logic die na een actie meedenkt.
   • Voorbeeld: Na "Wondzorg registratie" → Suggestie: "Wondcontrole inplannen?"

---

3. Userstories

User Story Template:

Als [rol] wil ik [actie] zodat [waarde].

ID	Rol	Doel / Actie	Context / Voorbeeld	Prioriteit
US-V2-01	Vpk	Multi-Intent commando's geven	"Meld Jan af voor vandaag en bel zijn huisarts."	Hoog
US-V2-02	Vpk	Context-aware begrepen worden	"Plan wondzorg morgen" (Snap dat 'morgen' refereert aan mijn agenda).	Hoog
US-V2-03	Regie	Proactieve checks op veiligheid	Bij voorschrijven lithium: "Check laatste nierfunctie?"	Middel
US-V2-04	Psych	Impliciete intenties verwerkt zien	"Patiënt was suïcidaal" → Systeem oppert crisisprotocol start.	Hoog
US-V2-05	Vpk	Geen "Computer says no" ervaring	Bij twijfel: vraag verduidelijking i.p.v. "Ik begrijp het niet".	Hoog

---

4. Functionele werking per onderdeel

4.1 Layer 1: The Reflex Arc (Local First)

• Trigger: Elke gebruikersinput (spraak/tekst).
• Werking: Checkt razendsnel (<20ms) of de input matcht met een Local Pattern (Regex).
• Conditie: Alleen bij Confidence >= 0.7 (industry standard) voert hij direct uit.
• Fallback: Bij twijfel (<0.7), ambiguïteit (top-2 delta <0.1), of escalatie-triggers → Direct doorsturen naar Layer 2.

4.2 Layer 2: The Intent Orchestrator (AI Router)

• Trigger: Input die te complex of dubbelzinnig is voor Layer 1.
• Input Context: Ontvangt niet alleen de zin, maar ook: ActivePatient, CurrentView, Time.
• Werking:
  1. Analyseert intentie(s).
  2. Splits samengestelde zinnen ("En", "Daarna") in een Action Chain.
  3. Extraheert entities (Wie, Wanneer, Wat).
• Output: Een lijst van uit te voeren acties: [ActionA, ActionB].

4.3 Layer 3: The Nudge (Post-Action Logic)

• Trigger: Succesvolle afronding van een intent (bijv. CreateAppointment klaar).
• Werking: Draait Domain Rules op de uitgevoerde actie.
• UI: Toont een Suggestion Toast of Card ("Wil je ook...?").
• Voorbeeld:
  • Actie: Medicatie gestart.
  • Rule: "Nieuwe medicatie vereist evaluatie na 2 weken."
  • Suggestie: "Evaluatie afspraak inplannen over 14 dagen?"

---

5. UI-overzicht (Flow)

De UI past zich aan op basis van de complexiteit van de intentie.

┌─────────────────────────────────────────────────────────────┐
│ 1. Input: "Zeg Jan af en maak notitie: grieperig"           │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Processing (Cortex): "1 moment, ik verwerk 2 acties..."  │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Execution UI (Stacked Cards)                             │
│ ┌──────────────────────────────────────┐                    │
│ │ ✅ Afspraak Jan (14:00) Geannuleerd  │                    │
│ └──────────────────────────────────────┘                    │
│ ┌──────────────────────────────────────┐                    │
│ │ 📝 Concept Notitie: "grieperig"      │ [Bevestigen]       │
│ └──────────────────────────────────────┘                    │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Nudge (Proactive Toast)                                  │
│ 💡 "Wil je de griep-poli waarschuwen?"   [Ja, doe maar] [X] │
└─────────────────────────────────────────────────────────────┘

---

6. Interacties met AI (Specificaties)

Component	Trigger	AI Model	Prompt Strategie	Output Structuur
Reflex	User Input	Geen (Regex)	N.v.t.	SingleIntent
Cortex	Complex Input	Claude 3.5 Haiku	"You are an Orchestrator. Output a JSON list of intents."	Array<IntentAction>
Safety	Action Done	Regelset / Small AI	"Based on this action, what is the protocol?"	`Suggestion

6.1 Multi-Intent Data Model

Het systeem moet worden omgebouwd van Single Intent naar Intent Chain:

Oud:

interface Result { intent: CortexIntent }

Nieuw:

interface IntentChain {
  originalInput: string;
  actions: IntentAction[];
}

interface IntentAction {
  intent: CortexIntent;
  entities: ExtractedEntities;
  status: 'pending' | 'success' | 'failed';
  requiresConfirmation: boolean;
}

---

7. Migratie & Roadmap

Fase 1: Hybrid Foundation (Week 1-2)

• Implementatie van de Reflex/Cortex switch.
• Zorgen dat alle twijfelgevallen naar de AI gaan (geen "Unknown" errors meer).
• Context object (ActivePatient) meegeven aan AI.

Fase 2: Orchestration (Week 3-4)

• Refactor frontend om IntentChain (lijstjes) te ondersteunen.
• Prompt engineering voor multi-intent herkenning ("En", "Daarna").

Fase 3: Proactivity (Maand 2)

• Bouwen van de Nudge listeners.
• Protocollen toevoegen voor Medicatie en Wondzorg.

---

8. Bijlagen & Referenties

• PRD/Vision: docs/intent/ux-simulation-intent-next-level.md
• Technical Base: lib/cortex/intent-classifier-ai.ts
• Legacy Docs: docs/intent/intent-architecture-v2-proposal.md