mindnet/docs/06_Roadmap/06_handover_prompts.md

doc_type	audience	status	version	context
operations	developer, admin	active	1.0	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.

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).

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.

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".

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.

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.

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.

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!

---

WP-22: Content Lifecycle & Meta-Config

Status: 🚀 Startklar Fokus: Ingestion-Filter, Scoring-Logik, Registry-Architektur.

Du bist der Lead Architect für "Mindnet" (v2.7).
Wir starten ein umfassendes Architektur-Paket: **WP-22: Graph Intelligence & Lifecycle**.

**Kontext:**
Wir professionalisieren die Datenhaltung ("Docs as Code") und machen die Suche kontextsensitiv.
Wir haben eine Markdown-Datei (`01_edge_vocabulary.md`), die als Single-Source-of-Truth für Kanten-Typen dient.

**Dein Auftrag:**
Implementiere (A) den Content-Lifecycle, (B) die Edge-Registry und (C) das Semantic Routing.

### Teil A: Content Lifecycle (Ingestion Logic)
Steuerung über Frontmatter `status`:
1.  **System-Dateien (No-Index):**
    * Wenn `status` in `['system', 'template']`: **Hard Skip**. Datei wird nicht vektorisiert.
2.  **Wissens-Status (Scoring):**
    * Wenn `status` in `['draft', 'active', 'stable']`: Status wird im Payload gespeichert.
    * **ToDo:** Erweitere `scoring.py`, damit `stable` Notizen einen Bonus erhalten (`x 1.2`), `drafts` einen Malus (`x 0.5`).

### Teil B: Central Edge Registry & Validation
1.  **Registry Klasse:**
    * Erstelle `EdgeRegistry` (Singleton).
    * Liest beim Start `01_User_Manual/01_edge_vocabulary.md` (Regex parsing der Tabelle).
    * Stellt `canonical_types` und `aliases` bereit.
2.  **Rückwärtslogik (Learning):**
    * Prüfe beim Import jede Kante gegen die Registry.
    * Unbekannte Typen werden **nicht** verworfen, sondern in `data/logs/unknown_edges.jsonl` geloggt (für späteres Review).

### Teil C: Semantic Graph Routing (Dynamic Boosting)
**Ziel:** Die Bedeutung einer Kante soll sich je nach Frage-Typ ändern ("Warum" vs. "Wie").

**Architektur-Vorgabe (WICHTIG):**
Die Gewichtung findet **Pre-Retrieval** (im Scoring-Algorithmus) statt, **nicht** im LLM-Prompt.

1.  **Decision Engine (`decision_engine.yaml`):**
    * Füge `boost_edges` zu Strategien hinzu.
    * *Beispiel:* `EXPLANATION` (Warum-Fragen) -> Boost `caused_by: 2.5`, `derived_from: 2.0`.
    * *Beispiel:* `ACTION` (Wie-Fragen) -> Boost `next: 3.0`, `depends_on: 2.0`.
2.  **Scoring-Logik (`scoring.py`):**
    * Der `Retriever` erhält vom Router die `boost_edges` Map.
    * Berechne Score: `BaseScore * (1 + ConfigWeight + DynamicBoost)`.


**Deine Aufgaben:**
1.  Zeige die `EdgeRegistry` Klasse (Parsing Logik).
2.  Zeige die Integration in `ingestion.py` (Status-Filter & Edge-Validierung).
3.  Zeige die Erweiterung in `scoring.py` (Status-Gewicht & Dynamic Edge Boosting).

Bitte bestätige die Übernahme dieses Architektur-Pakets.

WP24

Übergabe Arbeitspaket: WP-24 – Proactive Discovery & Agentic Knowledge Mining

## 1. Projekt-Kontext
Wir arbeiten an **Mindnet**, einem System für einen "digitalen Zwilling". Das System nutzt einen Wissensgraph (Qdrant), asynchrone Ingestion und eine hybride LLM-Infrastruktur (Cloud/Lokal).

## 2. Status Quo (Abgeschlossen: WP-15b)
Das Arbeitspaket **WP-15b (Candidate-Based Validation)** wurde gerade erfolgreich implementiert. 
* **Two-Pass Workflow:** In Pass 1 wird ein globaler `LocalBatchCache` aufgebaut (ID, Titel, Dateiname). In Pass 2 findet eine semantische binäre Validierung (YES/NO) statt.
* **Edge Inheritance:** Kanten werden aus Sektionen und Frontmatter an Chunks vererbt.
* **Candidate Pool:** Nur Kanten in der Sektion `## Unzugeordnete Kanten` (Provenienz: `global_pool`) werden vom LLM geprüft. Explizite Kanten (`[!edge]` im Text) werden direkt übernommen.

## 3. Auftrag: WP-24 – Proactive Discovery & Agentic Knowledge Mining
Das Ziel ist die Transformation von Mindnet zu einem aktiven Denkpartner.

### Teil A: Proactive Discovery (Vault-Scanning)
* **Mechanismus:** Automatisches Befüllen des `candidate_pool` via Vektor-Ähnlichkeit.
* **Logik:** Beim Import einer Note sucht ein neuer Service in Qdrant nach den semantisch ähnlichsten Chunks im Vault und fügt diese als `related_to` Kandidaten hinzu.
* **Filter:** Die WP-15b Validierungs-Logik filtert diese Vorschläge anschließend.

### Teil B: Agentic Knowledge Mining (Chat-to-Vault)
* **Mechanismus:** Extraktion notierwürdiger Informationen aus dem Chat.
* **Logik:** Erstellung von Markdown-Drafts im `00_Inbox` Ordner basierend auf dem Chat-Kontext unter Nutzung des `interview_template`.

## 4. Erforderliche Code-Basis (Dateien)
Stelle sicher, dass dir folgende Dateien vorliegen, um die Logik zu verstehen und zu erweitern:

1.  **`app/core/ingestion.py` (v2.12.2):** Zentraler Two-Pass Workflow und Validierungsgate.
2.  **`app/core/chunker.py` (v3.2.0):** Vorbereitung des Candidate-Pools und Vererbungslogik.
3.  **`scripts/import_markdown.py` (v2.4.1):** Entry-Point und Pre-Scan Harvester für den Cache.
4.  **`app/core/derive_edges.py` (v2.1.0):** Aggregator für Kanten mit Provenance-Priorisierung.
5.  **`app/services/edge_registry.py` (v0.8.0):** Validierung gegen das Kanten-Vokabular.
6.  **`config/prompts.yaml` (v2.6.0):** Enthält die `edge_validation` und `interview_template` Prompts.
7.  **`06_active_roadmap.md` (v2.9.0):** Enthält die detaillierte Planung für WP-24.

## 5. Nächste technische Schritte
1.  Entwurf eines `RecommenderService` für die Vektor-Suche in Qdrant.
2.  Integration des Services in die `ingestion.py` zur automatischen Befüllung des `candidate_pool`.
3.  Erweiterung des Chat-Backends um die "Capture-to-Vault" Funktionalität.

WP-25: Advanced Reasoning Engine (Agentic RAG)

**Status:** 🚀 High-Priority Upgrade
**Ziel:** Implementierung einer mehrstufigen Entscheidungs-Architektur ("Multi-Hop").


**Das Problem:**
Single-Step-Retrieval verwässert Ergebnisse. Eine Suche nach "Projekt-Entscheidung" findet oft operative Details, übersieht aber fundamentale Werte ("Wertekompass"), weil diese semantisch distanziert sind.

**Die Lösung (Architektur):**
Wir ersetzen die flache Suche durch eine **Orchestrator-Logik**, die parallele Streams ausführt.

---

### Teil A: Configuration Upgrade (`decision_engine.yaml`)
Erweitere die Config-Struktur, um statt einfacher Listen echte **Sub-Queries** zu definieren.

*Neu (Vorschlag):*
````yaml
strategies:
  DECISION:
    description: "Komplexe Abwägung"
    # Der Orchestrator führt diese 3 Streams parallel aus:
    streams:
      - name: "facts"
        query_template: "Status und Fakten zu: {query}"
        filter_types: ["project", "journal", "decision"]
        edge_boosts: {part_of: 1.5}
      
      - name: "values"
        query_template: "Welche Werte und Prinzipien sind relevant für: {query}"
        filter_types: ["value", "principle", "belief"]
        edge_boosts: {derived_from: 2.0, enforced_by: 2.0} # Findet den "Wertekompass"!
      
      - name: "risks"
        query_template: "Risiken und Gefahren bei: {query}"
        filter_types: ["risk", "obstacle"]
        edge_boosts: {blocks: 2.5, impacts: 2.0}

### Teil B: Implementation (`DecisionEngine.py`)
1.  **Decomposition:** Wenn eine Strategie `streams` definiert, darf nicht mehr *ein* `retrieve()` Aufruf erfolgen.
2.  **Parallel Execution:**
    * Iteriere über alle Streams.
    * Führe für jeden Stream einen eigenen `retriever.retrieve()` aus – mit dessen spezifischen Filtern, Query und Edge-Boosts.
3.  **Intermediate Summarization (Optional/Later):**
    * (Für Version 1 reicht es, die Ergebnisse der Streams in markierten Blöcken an den Prompt zu geben).

### Teil C: The Synthesis (Prompting)
Passe das Prompt-Template an, um die getrennten Streams zu nutzen:

...
HIER SIND DIE FAKTEN:
{stream_results_facts}

HIER SIND DIE RELEVANTEN WERTE/PRINZIPIEN:
{stream_results_values}

HIER SIND DIE RISIKEN:
{stream_results_risks}

AUFGABE: Wäge die Fakten gegen die Werte ab.

---

Deine Aufgaben:

1. Refactor Config: Zeige, wie die decision_engine.yaml für Multi-Stream angepasst wird.
2. Orchestrator Logic: Schreibe die Python-Logik, die diese Streams parallel abfeuert und die Ergebnisse aggregiert.
3. Integration: Nutze die EdgeRegistry (aus WP-22) für die Boosts in jedem Stream.

Bitte bestätige die Übernahme dieser "Agentic Architecture" (WP-25).