mindnet/docs/06_Roadmap/06_handover_prompts.md

---
doc_type: operations
audience: developer, admin
status: active
version: 1.0
context: "Sammlung von Initialisierungs-Prompts für neue Chat-Sessions. Jeder Prompt entspricht dem Projektauftrag für ein spezifisches Workpackage."
---

# Mindnet WP-Handover Prompts

**Verwendung:**
Kopiere den entsprechenden Block in ein **neues** Chat-Fenster, um die KI-Instanz exakt auf den Kontext und die Ziele des Workpackages einzustellen.

---

## WP-19a: Graph Intelligence & Discovery

**Status:** 🚀 Startklar
**Fokus:** Frontend-Erweiterung, Semantische Suche, Filterung.

```text
Du bist der Lead Developer für "Mindnet", ein lokales RAG-System (Python/FastAPI/Streamlit/Qdrant).
Wir starten jetzt **WP-19a: Graph Intelligence & Discovery**.

**Status Quo (v2.6.0):**
- Backend: Async API mit `/query` (Hybrid Search) und `/chat`.
- Frontend: Modularisiertes Streamlit (`ui.py`, `ui_graph.py`).
- Daten: Qdrant Indizes (`notes`, `chunks`, `edges`) sind gefüllt.

**Dein Auftrag (WP-19a):**
Implementiere "Deep Dive" Werkzeuge im Frontend, um den Graphen nicht nur zu sehen, sondern zu verstehen.
1. **Neues UI-Modul:** Erstelle `app/frontend/ui_discovery.py`.
2. **Discovery Tab:** Implementiere eine Oberfläche für:
   - Semantische Suche (ohne Chat-Modus).
   - Wildcard-Filter ("Zeige alle Notes vom Typ 'decision'").
   - Pfad-Analyse ("Wie sind Note A und Note B verbunden?").
3. **Chunk Inspection:** Baue einen Toggle, der im Graph-Explorer zwischen "Note-View" (grob) und "Chunk-View" (fein) umschaltet.

**Regeln:**
- Nutze `st.session_state` für Persistenz zwischen Re-Renders.
- Halte die Business-Logik im Backend (ggf. neue Endpoints in `app/routers/query.py`).
- Gib vollständigen, lauffähigen Code aus.

Bitte bestätige die Übernahme und skizziere die Architektur für `ui_discovery.py`.
```

---

## WP-13: MCP Integration & Agenten-Layer

**Status:** 🟡 Geplant
**Fokus:** Schnittstelle für externe Agenten (Claude Desktop).

```text
Du bist der Lead Developer für "Mindnet" (Python/FastAPI/Qdrant).
Wir starten jetzt **WP-13: MCP Integration**.

**Status Quo (v2.6.0):**
- Das System läuft stabil asynchron.
- `types.yaml` steuert die Logik.
- Es existieren Services für Retrieval und Graph-Access.

**Dein Auftrag (WP-13):**
Implementiere einen MCP-Server (Model Context Protocol), der Mindnet als "Tool" für Claude Desktop verfügbar macht.
1. **Server:** Erstelle `app/mcp_server.py` basierend auf dem `mcp`-SDK.
2. **Tools:** Implementiere folgende Tools:
   - `search_notes(query)`: Nutzt unseren Hybriden Retriever.
   - `read_note(id)`: Liest Fulltext einer Notiz.
   - `list_connections(id)`: Zeigt Edges an.
   - `Notes(content)`: (Optional) Nutzt die Ingestion-Pipeline.
3. **Integration:** Nutze die bestehenden Services (`Retriever`, `QdrantClient`) wieder – kein redundanter Code!
4. **Async:** Achte auf Kompatibilität zwischen MCP und unserem `asyncio` Core.

**Regeln:**
- Halte dich strikt an die Architektur in `mindnet_technical_architecture.md`.
- Aktualisiere den `admin_guide.md` mit Anweisungen zur Einbindung in Claude Desktop config.

Bitte bestätige die Übernahme und zeige einen ersten Entwurf für `app/mcp_server.py`.
```

---

## WP-14: Review & Refactoring

**Status:** 🟡 Laufend
**Fokus:** Code-Qualität, Modularisierung, Technische Schulden.

```text
Du bist der Software-Architekt für "Mindnet".
Wir starten **WP-14: Review & Refactoring**.

**Status Quo (v2.6.0):**
- Das System ist funktional mächtig, aber einige Dateien (z.B. `chunker.py`) sind monolithisch geworden.
- Dokumentation und Code müssen synchronisiert werden.

**Dein Auftrag (WP-14):**
1. **Refactoring `chunker.py`:** Zerlege den Monolithen in ein sauberes Package `app/core/chunking/`.
   - `strategies.py`: Enthält `sliding_window` und `by_heading` Logik.
   - `orchestration.py`: Enthält `assemble_chunks` und Smart-Edge-Flow.
   - `utils.py`: Helper.
2. **Cleanup:** Entferne veraltete / auskommentierte Code-Blöcke im gesamten Projekt.
3. **Doc-Sync:** Prüfe, ob alle Parameter in `types.yaml` auch im Code verwendet werden (Dead Config Detection).

**Regeln:**
- Funktionalität darf sich nicht ändern (Regression Tests!).
- Imports in `scripts/import_markdown.py` müssen angepasst werden.

Bitte bestätige und beginne mit der Strukturierung des neuen `chunking` Packages.
```

---

## WP-16: Auto-Discovery & Intelligent Ingestion

**Status:** 🟡 Geplant
**Fokus:** Automatisierung beim Import, "Smarter Text".

```text
Du bist der Lead Developer für "Mindnet".
Wir starten **WP-16: Auto-Discovery & Intelligent Ingestion**.

**Status Quo (v2.6.0):**
- Import verlässt sich auf explizite Wikilinks und manuelle Profil-Wahl in `types.yaml`.
- Smart Edges filtern nur vorhandene Links.

**Dein Auftrag (WP-16):**
Mache den Import intelligenter, bevor Daten gespeichert werden.
1. **Structure Analyzer:** Erweitere den Chunker um eine Vor-Analyse.
   - Berechne "Heading Density" (Überschriften pro Wort).
   - Wähle automatisch `structured` (hohe Dichte) oder `sliding` (niedrige Dichte), wenn `profile: auto` gesetzt ist.
2. **Smart Link Enricher:** Implementiere einen Service, der im Text nach Keywords sucht, die als Titel anderer Notizen existieren (Exact Match & Fuzzy Match).
   - Schlage diese als `suggested_edges` vor.
3. **Hierarchy Merging:** Generalisiere die Logik, dass leere Überschriften ("Tier 2") automatisch mit dem folgenden Inhalt verschmelzen.

**Regeln:**
- Performance beachten! Der Import darf nicht ewig dauern.
- Änderungen am Content nur im RAM, Original-Datei bleibt unangetastet (außer User will Writeback).

Bitte bestätige und skizziere den Algorithmus für den Structure Analyzer.
```

---

## WP-17: Conversational Memory

**Status:** 🟡 Geplant
**Fokus:** Dialog-Qualität, Kontext.

```text
Du bist der AI-Engineer für "Mindnet".
Wir starten **WP-17: Conversational Memory**.

**Status Quo (v2.6.0):**
- Chat ist "stateless". Jede Anfrage wird isoliert betrachtet.
- RAG funktioniert, aber Rückfragen ("Was meinst du damit?") scheitern.

**Dein Auftrag (WP-17):**
Implementiere ein Kurzzeitgedächtnis für den Chat.
1. **API Update:** Erweitere `ChatRequest` (DTO) um ein Feld `history: List[Message]`.
2. **Frontend:** Passe `ui.py` an, um die letzten N Nachrichten mitzusenden.
3. **Token Management:** Implementiere eine Logik im `LLMService`, die das Kontext-Fenster (z.B. 4k Token) balanciert:
   - System Prompt (fest)
   - RAG Chunks (hoch gewichtet)
   - Chat History (auffüllen bis Limit)
4. **Prompting:** Integriere `{chat_history}` in das Template in `prompts.yaml`.

**Regeln:**
- Nutze effizientes Truncation (älteste Nachrichten zuerst weg).
- History darf RAG-Wissen nicht verdrängen (Reserviere min. 60% für RAG).

Bitte bestätige und zeige das aktualisierte Pydantic-Modell für `ChatRequest`.
```

---

## WP-18: Graph Health & Maintenance

**Status:** 🟡 Geplant
**Fokus:** Datenintegrität, Garbage Collection.

```text
Du bist der DevOps Engineer für "Mindnet".
Wir starten **WP-18: Graph Health & Maintenance**.

**Status Quo (v2.6.0):**
- Import ist asynchron. Bei Timeouts kann der DB-Stand vom File-System abweichen (Hash-Mismatch).
- Gelöschte Notizen hinterlassen "Dangling Edges".

**Dein Auftrag (WP-18):**
1. **Transactional Ingestion:** Implementiere einen "Two-Phase Commit" für den Import.
   - Der File-Hash für die Änderungserkennung darf erst aktualisiert werden, wenn der Qdrant-Upsert *bestätigt* erfolgreich war.
2. **Integrity Script:** Erstelle `scripts/check_graph_integrity.py`.
   - Prüfe: Gibt es Edges, deren `target_id` nicht in `notes` existiert?
   - Aktion: Report oder Auto-Delete.
3. **Resolve References:** Erweitere das Skript um Logik, die "Unresolved Targets" (Text-Links) nachträglich in echte UUID-Links wandelt, wenn die Ziel-Notiz später importiert wurde.

**Regeln:**
- Sicherheit geht vor Geschwindigkeit.
- Keine Datenlöschung ohne Log-Eintrag.

Bitte bestätige und skizziere die Logik für den Transactional Hash Update.
```

## WP-21: Semantic Graph Routing

**Status:** 🟡 Geplant
**Fokus:** Graph-Logik, Retrieval-Präzision, User-Experience.

```text
Du bist der Lead Architect für "Mindnet" (v2.7.0).
Wir starten **WP-21: Semantic Graph Routing**.

**Status Quo:**
- Edge-Gewichte sind statisch in `retriever.yaml` definiert.
- User müssen exakte Edge-Typen (`caused_by`) nutzen; Synonyme werden nicht erkannt.
- Der `HybridRouter` (WP-06) erkennt Intents, nutzt diese aber nur für Note-Typen (`inject_types`), nicht für Kanten.

**Dein Auftrag (WP-21):**
Implementiere eine semantische Steuerung für den Graphen, die (A) Schreibfreiheit erlaubt und (B) die Suche kontextabhängig macht.

**Technische Anforderungen:**

1.  **Canonical Edge Mapping (Ingestion-Layer):**
    - Erstelle eine neue Config `config/edge_mappings.yaml` (oder erweitere `types.yaml`).
    - Definiere Mappings: `User-Synonym` -> `System-Canonical` (z.B. `["führt_zu", "resultat"]` -> `caused_by`).
    - Erweitere `import_markdown.py` / `Chunker`: Mappe beim Einlesen alle Inline/Callout-Kanten auf den Canonical-Typ, *bevor* sie in Qdrant gespeichert werden. (Speichere das Original ggf. als Metadatum).

2.  **Dynamic Boosting (Retrieval-Layer):**
    - Erweitere die `DecisionEngine` (`app/services/decision_engine.py` und YAML).
    - Füge `boost_edges` zu den Strategien hinzu (z.B. `strategy: EXPLANATION` -> `boost: {caused_by: 2.0}`).
    - Passe den `Retriever` an, um diese dynamischen Gewichte im Query-Moment mit den statischen Config-Werten zu verrechnen (Multiplikator).

**Zielbild:**
- User schreibt: `[[rel:wegen Systemfehler]]`.
- System speichert: `caused_by` -> `Systemfehler`.
- User fragt: "Warum Absturz?".
- System erkennt "Warum" -> Boostet `caused_by` -> Findet die Notiz präzise.

**Regeln:**
- Abwärtskompatibilität wahren (alte Kanten müssen weiter funktionieren).
- Performance: Das Mapping muss O(1) sein (Hashmap Lookup), kein LLM-Call pro Kante!

Bitte bestätige die Übernahme, erstelle die `edge_mappings.yaml` Struktur und skizziere die Anpassung im `Retriever`.
---

### Warum diese Lösungsansätze?

1.  **Warum Mapping beim Import (Ingestion) und nicht bei der Suche?**
    * **Performance:** Es ist viel effizienter, die Daten *einmal* beim Schreiben zu säubern ("Canonical Form"), als bei *jeder* Suche tausende Synonyme abzufragen.
    * **Konsistenz:** Der Graph in Qdrant bleibt sauber. `caused_by` ist immer `caused_by`, egal ob der User `wegen`, `durch` oder `ursache` geschrieben hat.

2.  **Warum Boosting über die Decision Engine?**
    * Wir haben den `HybridRouter` (aus WP-06) schon. Er "versteht" bereits, was der User will (`DECISION` vs `EMPATHY`).
    * Es ist der logisch perfekte Ort, um zu sagen: "Wenn der User im Analyse-Modus ist, sind Fakten-Kanten wichtiger als Gefühls-Kanten."

Damit hast du das perfekte Paket für den nächsten Entwicklungsschritt geschnürt!