mindnet/Programmmanagement/Dokumentationsrahmenplan.md

mindnet v2.2 – Dokumentationsrahmenplan

Datei: docs/mindnet_docs_master_plan_v2.2.md
Stand: 2025-12-06
Bezug: Programmplan mindnet v2.2 :contentReference[oaicite:0]{index=0}

---

1. Zweck dieses Rahmenplans

Dieser Rahmenplan definiert:

• die Zieldokumente der mindnet v2.2 Dokumentation,
• deren Dateinamen, Zielgruppen, Inhalte und Quellen,
• die Zuordnung zu Workpackages (WP) und Release-Tags,
• die Regeln zum Informations-Erhalt (keine inhaltlichen Verluste),
• die empfohlene Bearbeitungsreihenfolge.

Alle hier beschriebenen Zieldokumente werden als eigene Markdown-Dateien gepflegt und sind Teil von WP-14 Review / Refactoring / Dokumentation (Phase E). :contentReference[oaicite:1]{index=1}

---

2. Prinzipien zur Sicherung der Informationen

Um zu verhindern, dass Inhalte oder Ergebnisse verloren gehen, gelten folgende Prinzipien:

1. Programmplan v2.2 als Masterreferenz

   • Programmauftrag, Vision, Phasenmodell und WP-Status werden nicht verändert, sondern nur referenziert.
   • Programmplan_V2.2.md bleibt das führende Dokument für Ziele, WPs, Ampelstatus. :contentReference[oaicite:2]{index=2}

2. Keine unkontrollierte Löschung von Inhalten

   • Bestehende Dokumente (knowledge_design.md, chunking_strategy.md, mindnet_technical_architecture.md, Handbuch.md, TYPE_REGISTRY_MANUAL.md, docs_mindnet_retriever.md, wp04_retriever_scoring.md) werden nicht gelöscht, sondern:
     • vollständig archiviert,
     • in die neuen Zieldokumente überführt,
     • oder explizit in den Anhängen (I) als „legacy / historisch“ verlinkt.

3. Explizite Quellenzuordnung („Building Blocks“)

   • Für jede Sektion eines Zieldokuments wird angegeben, aus welchen bestehenden Dateien und Abschnitten der Inhalt stammt.
   • Neue Inhalte (z. B. User Guide H) werden klar als „neu, v2.2“ gekennzeichnet.

4. Ist-Stand vs. Roadmap trennen

   • Implementierter Stand v2.2: WP01–WP04a (🟢) mit Importer, Chunking, Edge-Pipeline, Typ-Registry und hybrider Retriever.
   • Geplante Features (Self-Healing, Virtual Schema Layer, Explanation Layer, Feedback-Logging, MCP-Agenten) werden als Roadmap-Funktionen kenntlich gemacht (Phase B–D, WPs 05–13).

5. Versionierbarkeit

   • Alle Zieldokumente tragen im Kopf eine Version und Stand-Datum sowie optional einen Verweis auf den letzten Gitea-Tag (z. B. mindnet_v2.2_docs_initial, WP04a-Retriever_final). :contentReference[oaicite:6]{index=6}
   • Änderungen werden im Abschnitt „Changelog“ der jeweiligen Datei notiert.

6. Keine funktionalen Annahmen ohne Verifikation

   • Wo das Verhalten nicht eindeutig aus Code-/Handbuch-/WP-Dokumenten hervorgeht, wird der Punkt zunächst als offene Frage markiert und nicht als Tatsache dokumentiert.
   • Verifizierte Funktionen (z. B. import_markdown, Edge-Schema, types.yaml, /query, Scoring-Formel) werden exakt gemäß der bestehenden Dokumente beschrieben.

---

3. Zieldokumente der mindnet v2.2 Dokumentation

3.1 Übersichtstabelle

ID	Zieldatei	Rolle/Zielgruppe	Hauptquellen (Building Blocks)
A	mindnet_overview_v2.2.md	Einstieg für alle Rollen	Programmplan v2.2, Knowledge Design
B	mindnet_functional_architecture_v2.2.md	Architekt:innen, Mindmaster	Knowledge Design, Functional Architecture, Programmplan
C	mindnet_technical_architecture_v2.2.md	Entwickler:innen, Tech-Architekt:innen	mindnet_technical_architecture, chunking_strategy, Handbuch
D	mindnet_knowledge_design_manual_v2.2.md	Vault-Autor:innen, Mindmaster, Analyst:innen	knowledge_design, TYPE_REGISTRY_MANUAL, Functional Architecture
E	mindnet_pipeline_playbook_v2.2.md	Dev/Ops, Tech-Lead	mindnet_v2_implementation_playbook, Handbuch, chunking_strategy, docs_mindnet_retriever, wp04_retriever_scoring
F	mindnet_developer_guide_v2.2.md	Entwickler:innen (Code, API, Tests)	Technical Architecture, Handbuch, docs_mindnet_retriever
G	mindnet_admin_guide_v2.2.md	Admins, Betreiber	Handbuch, Implementation Playbook, Programmplan (Governance)
H	mindnet_user_guide_v2.2.md	Endnutzer:innen, Agent-User	Knowledge Design, Programmplan (Use Cases), spätere MCP-WPs
I	mindnet_appendices_v2.2.md	Alle Rollen (Referenzen, Tabellen)	TYPE_REGISTRY_MANUAL, chunking_strategy, WP-Übersicht, Edge-Referenz

---

4. Detailpläne pro Zieldokument (Inhaltsverzeichnis & Building Blocks)

A) mindnet_overview_v2.2.md

Zweck & Zielgruppe

• Einstieg in mindnet für alle Rollen (Owner, Mindmaster, Developer, Admin, Agenten-Entwickler).
• Auf 3–5 Seiten: Was ist mindnet? Wie ist es gedacht? Wie lese ich die Dokumentation? :contentReference[oaicite:17]{index=17}

Geplantes Inhaltsverzeichnis

1. Einführung
   1. Programmauftrag & Vision (v2.2)
   2. Was mindnet ist – und was nicht
2. Drei Ebenen von mindnet
   1. Content-Ebene (Vault, Notes, Chunks)
   2. Semantische Ebene (Edges, Typen, Retriever)
   3. Identitäts- / Persönlichkeits-Ebene (Werte, Entscheidungen, Profile – Roadmap)
3. End-to-End-Überblick
   1. Datenfluss: Vault → Import → Qdrant → Retriever → Antwort
   2. WP-Phasenmodell (A–E) und aktueller Stand (WP01–04a grün)
4. Rollen & Perspektiven
   1. Mindmaster / Owner
   2. Autor:in (Vault-Notes)
   3. Developer / Architect
   4. Administrator:in
   5. Agenten & LLMs (MCP-Perspektive)
5. Leserführung durch die Dokumentation
   1. Welche Datei für welche Rolle?
   2. Wie mit Ist-Stand vs. Roadmap umgehen?
6. Glossar zentraler Begriffe
   • mindnet, Vault, Note, Chunk, Edge, Type, Identity, Self-Healing, Self-Tuning, Explanation Layer, Virtual Schema Layer, etc.

Building Blocks (Quellen-Mapping)

• Programmauftrag & Vision → Programmplan_V2.2.md, Kapitel 1–2. :contentReference[oaicite:18]{index=18}
• Phasenmodell & WPs → Programmplan_V2.1.md/v2.2, Kapitel 5–9 (angepasst auf v2.2-Stand).
• High-Level-Architektur → knowledge_design.md, Kapitel 1–3 (Ziel, Zielarchitektur, Collections). :contentReference[oaicite:20]{index=20}
• Rollenmodell → Ableitung aus Knowledge Design + Programmplan (Owner, Agenten, MCP-WPs).

---

B) mindnet_functional_architecture_v2.2.md

Zweck & Zielgruppe

• Fachliche Architektur von mindnet (Konzeptmodell).
• Für Architekt:innen, Mindmaster, Knowledge-Designer.

Geplantes Inhaltsverzeichnis

1. Ziel & Einordnung
   1. Bezug zu Programmauftrag & WPs (WP01–WP07, WP10–12)
2. Kernkonzepte
   1. Notes & Note-Typen (concept, experience, project, decision, value, principle, person, event, …)
   2. Chunks & Sections
   3. Edges (Struktur, explizit, inline, Default-Kanten)
   4. Typen-Registry & Virtual Schema Layer (fachliche Sicht, Roadmap)
3. Graph-Modell
   1. Knotenarten (Notes, Chunks, Identity Nodes, People)
   2. Kantenarten (belongs_to, references, similar_to, depends_on, related_to, next/prev, …)
   3. Scope & Provenienz (chunk vs. note, rule_id, confidence)
4. End-to-End fachlicher Datenfluss
   1. Erfassung von Wissen (Note erstellen)
   2. Import & Graphaufbau
   3. Retrieval & Begründungspfade
   4. Self-Healing & Retroactive Edges (WP06/07 – Roadmap)
5. Szenarien & Use Cases
   1. Wissensspeicherung (z. B. Leitbild, Projekt, Erfahrung)
   2. Entscheidungen & Why-Layer (WP04b – Roadmap)
   3. Persönlichkeits-/Identitätsmodell (WP10–12 – Roadmap)
6. Rollenmodell (fachliche Sicht)
   1. Mindmaster
   2. Content-Autor:innen
   3. Analyst:innen (Graph-Leser)
7. Designprinzipien (fachlich)
   • Late Binding, Virtual Schema, Self-Healing, Minimalinvasives Schreiben etc.

Building Blocks

• knowledge_design.md – Kapitel 1–4, 6–7 (Ziel, Architektur, Collections, Identitäten, Prinzipien). :contentReference[oaicite:28]{index=28}
• mindnet_functional_architecture.md – alle Kapitel (Kernkonzepte, Edgetypen, Provenienz, Rollen). :contentReference[oaicite:29]{index=29}
• chunking_strategy.md – Edges, Datenmodell, Graph-Sicht. :contentReference[oaicite:30]{index=30}
• Programmplan – WPs 01–07, 10–12 für Roadmap-Features.

---

C) mindnet_technical_architecture_v2.2.md

Zweck & Zielgruppe

• Technische Architektur des Systems: Collections, Payload-Felder, Services, Schemata.
• Für Entwickler:innen und Tech-Architekt:innen.

Geplantes Inhaltsverzeichnis

1. Ziel & Scope
   1. Abgrenzung zur funktionalen Architektur
   2. Bezug zu WPs 02–04a, 05 (Schema, Importer, Retriever)
2. Systemübersicht
   1. Komponentenübersicht (Importer, Qdrant, Retriever-API, Embedding-Service, n8n/MCP-Ausblick)
   2. Ports, Dienste, Hauptverzeichnisse
3. Datenmodell in Qdrant
   1. Notes (mindnet_notes)
   2. Chunks (mindnet_chunks)
   3. Edges (mindnet_edges)
   4. Optionale Collections (mindnet_people, zukünftige)
4. Typ-Registry & Konfiguration
   1. config/types.yaml – Aufbau, Defaults, Typauflösung (Ist-Stand: Frontmatter-Overrides deaktiviert)
   2. config/retriever.yaml – Scoringgewichte, Edge-Typ-Gewichte :contentReference[oaicite:35]{index=35}
5. Import-Pipeline (technische Sicht)
   1. Discovery & Parsing (import_markdown.py)
   2. Hash-/Idempotenz-Mechanismus (ENV-Variablen, Baseline-Modi)
   3. Chunking (chunker.py, chunk_payload.py)
   4. Edge-Erzeugung (derive_edges.py)
   5. Roundtrip & Tests (Export & Vault-Vergleich)
6. Retriever-Architektur
   1. API (FastAPI-Endpunkt /query)
   2. Semantik- und Hybridmodus
   3. Subgraph & Graph-API (expand)
   4. Scoring-Formel und Komponenten (semantik, edges, centrality) :contentReference[oaicite:37]{index=37}
7. Offene technische Punkte / Roadmap
   1. Explanation Layer (WP04b)
   2. Feedback-Logging (WP04c)
   3. Virtual Schema Layer (WP05)
   4. Self-Healing & Self-Tuning (WP06–08)

Building Blocks

• mindnet_technical_architecture.md – Kerntext. :contentReference[oaicite:39]{index=39}
• chunking_strategy.md – Datenmodell & Chunk-Details. :contentReference[oaicite:40]{index=40}
• Handbuch.md – ENV, Skripte, Runbooks. :contentReference[oaicite:41]{index=41}
• wp04_retriever_scoring.md / docs_mindnet_retriever.md – Retriever-Details. :contentReference[oaicite:42]{index=42}

---

D) mindnet_knowledge_design_manual_v2.2.md

Zweck & Zielgruppe

• Konkrete Anleitung für das Schreiben und Strukturieren von Notes & Chunks im Vault.
• Für dich als Owner/Mindmaster und alle, die Notes erstellen.

Geplantes Inhaltsverzeichnis

1. Zweck & Scope
   1. Rolle des Vaults als „Source of Truth“
2. Note-Struktur & Frontmatter
   1. Pflicht- und optionale Felder (id, title, type, tags, status, created/updated, …)
   2. Empfehlungen für IDs, Pfade und Namenskonventionen
3. Note-Typen & Typ-Registry
   1. Übersicht der Typen (concept, project, experience, decision, value, principle, person, event, …)
   2. Typ-spezifische Einsatzempfehlungen
   3. Zusammenspiel mit types.yaml (retriever_weight, chunk_profile, edge_defaults)
4. Edges & Referenzen in Notes
   1. Wikilinks ([[Note]]) → references
   2. Inline-Relationen ([[rel:depends_on XYZ]], similar_to, related_to)
   3. Callout-Edges (> [!edge] …)
   4. Strukturkanten (Ordner, belongs_to)
5. Best Practices
   1. Beispiele für gut modellierte Notes (Projekt, Entscheidung, Erfahrung)
   2. Typische Anti-Patterns und wie man sie vermeidet
6. Langfristige Stabilität
   1. Virtual Schema Layer – was bedeutet das für Note-Autoren? (Wenig Änderungen in bestehenden Notes, Logik in Configs) :contentReference[oaicite:46]{index=46}

Building Blocks

• knowledge_design.md – Kerntext + Beispiele. :contentReference[oaicite:47]{index=47}
• TYPE_REGISTRY_MANUAL.md – Typ-Registry & Verhalten. :contentReference[oaicite:48]{index=48}
• mindnet_functional_architecture.md – ergänzende Konzepte & Edges. :contentReference[oaicite:49]{index=49}
• chunking_strategy.md – Inline-Relationen, Edges, Datenmodell. :contentReference[oaicite:50]{index=50}

---

E) mindnet_pipeline_playbook_v2.2.md

Zweck & Zielgruppe

• End-to-End-Playbook für die gesamte Pipeline:
  • Importer,
  • Chunking,
  • Edge-Erzeugung,
  • Retriever & Scoring,
  • (perspektivisch) Explanation Layer, Self-Healing, Self-Tuning.
• Für Dev/Ops und technische Leads.

Geplantes Inhaltsverzeichnis

1. Zweck & Einordnung
   1. Bezug zu WPs 02–04a (Ist) und 04b–08 (Roadmap)
2. Import-Pipeline (Runbook-Sicht)
   1. Inputs (Vault, Config-Files, ENV)
   2. Standardläufe (Initialimport, inkrementelle Updates, Sync-Deletes)
   3. Baseline-Builds & Hash-Modi
3. Chunking & Payload-Aufbau
   1. Chunk-Profile, Overlaps, Fenster
   2. Feldbesetzung (text, window, section_title, neighbors, …)
4. Edge-Erzeugung
   1. Strukturkanten (belongs_to, next, prev)
   2. Explizite Edges (Wikilinks, Inline-Relationen, Callouts)
   3. Typ-Default-Kanten aus types.yaml
5. Retriever & Scoring
   1. Konfiguration (retriever.yaml, ENV)
   2. Scoring-Formel und Parameter
   3. Semantik- vs. Hybridmodus
   4. Test- und Smoke-Suites
6. Quality Gates & Tests
   1. Roundtrip-Tests (Vault → Qdrant → Export)
   2. Chunk-Integrität und Fenster-Checks
   3. Retriever-Regressionstests
7. Ausblick: Self-Healing, Retroactive Edges, Self-Tuning
   1. Geplante Batch-Jobs und Feedback-Pipelines (WP06–08)

Building Blocks

• mindnet_v2_implementation_playbook.md – Policies, Teststrategie, KPIs. :contentReference[oaicite:57]{index=57}
• Handbuch.md – Skripte & Test-Runbooks. :contentReference[oaicite:58]{index=58}
• chunking_strategy.md – Chunk- & Edge-Strategie. :contentReference[oaicite:59]{index=59}
• docs_mindnet_retriever.md / wp04_retriever_scoring.md – Retriever-Praktiken & Tests. :contentReference[oaicite:60]{index=60}

---

F) mindnet_developer_guide_v2.2.md

Zweck & Zielgruppe

• Konzentrierte Sicht für Entwickler:innen:
  • wie das Projekt strukturiert ist,
  • wie man es lokal aufsetzt,
  • wie man neue Features implementiert/testet.

Geplantes Inhaltsverzeichnis

1. Projektstruktur
   1. Verzeichnisbaum (app/, scripts/, tests/, config/, …)
2. Lokale Entwicklungsumgebung
   1. Abhängigkeiten, venv, ENV
   2. Starten von Services (Qdrant, API, ggf. ollama)
3. APIs & Module
   1. Importer-Skripte
   2. Core-Module (Chunker, Edge-Engine, Retriever)
   3. FastAPI-Endpunkte (/query, evtl. Admin-Endpoints)
4. Tests & Debugging
   1. pytest-Suites
   2. Logging & Diagnoseskripte
5. Guidelines für Erweiterungen
   1. Neue Typen & Edge-Regeln
   2. Änderungen am Datenmodell
   3. Umgang mit Schema-Änderungen (Virtual Schema Layer)

Building Blocks

• mindnet_technical_architecture.md – Modul- & API-Beschreibungen. :contentReference[oaicite:63]{index=63}
• Handbuch.md – Skripte & Beispiele. :contentReference[oaicite:64]{index=64}
• docs_mindnet_retriever.md – API-Beispiele für den Retriever. :contentReference[oaicite:65]{index=65}

---

G) mindnet_admin_guide_v2.2.md

Zweck & Zielgruppe

• Betriebshandbuch für mindnet:
  • Installation,
  • Konfiguration,
  • Backup/Restore,
  • Monitoring,
  • Troubleshooting.

Geplantes Inhaltsverzeichnis

1. Zielgruppe & Scope
2. Initial Setup
   1. Voraussetzungen (Ubuntu, Docker/Qdrant, Python-Umgebung)
   2. ENV-Variablen & Config-Files (types.yaml, retriever.yaml)
3. Betrieb im Alltag
   1. Regelmäßige Imports
   2. Umgang mit Fehlermeldungen im Importer
   3. Health-Checks für Qdrant & API
4. Update-Prozess
   1. Vorgehen bei Schema-/Code-Updates
   2. Umgang mit neuen Typen und Policies
5. Backup & Restore
   1. Qdrant-Snapshots
   2. Vault-Backup (Obsidian)
   3. Konsistenzprüfungen
6. Monitoring & Logging
   1. typische Logquellen (Importer, API, n8n)
7. Governance & Sicherheit
   1. Bezug zur Programm-Governance (WP14, MCP-Sicherheit)

Building Blocks

• Handbuch.md – Betriebsskripte & ENV. :contentReference[oaicite:69]{index=69}
• mindnet_v2_implementation_playbook.md – Policies/Resilienz. :contentReference[oaicite:70]{index=70}
• Programmplan – Governance / WP14. :contentReference[oaicite:71]{index=71}

---

H) mindnet_user_guide_v2.2.md

Zweck & Zielgruppe

• Anleitung für Nutzer:innen (inkl. späterer Chat-Agenten-User):
  • wie man mindnet im Alltag nutzt,
  • wie man Fragen stellt,
  • wie man neue Gedanken einbringt.

Geplantes Inhaltsverzeichnis

1. Was mindnet für dich tut
   1. Persönliches Gedächtnis
   2. KI-Zwilling als Gesprächspartner :contentReference[oaicite:72]{index=72}
2. Zugänge zu mindnet
   1. Obsidian-Vault
   2. Chat-Agent (lokal, n8n-Workflows)
   3. (später) Interview-Assistent, MCP-Tools
3. Gute Fragen an mindnet
   1. Beispiel-Queries (Wissensabruf, Entscheidungen, Reflexionen)
4. Neue Inhalte eingeben
   1. Notes in Obsidian erstellen
   2. Typen und Links bewusst setzen (vereinfachte Version aus D)
5. Ergebnisse interpretieren
   1. Was bedeutet ein Treffer-Set?
   2. Wie sind Scores zu lesen? (nur Ist-Stand, Explanation Layer als Ausblick)
6. Feedback & Lernen
   1. Manuelles Feedback (gut/schlecht) – Roadmap WP04c/08

Building Blocks

• Programmplan – Vision & Use-Cases. :contentReference[oaicite:76]{index=76}
• Knowledge Design – Autorensicht (stark vereinfacht). :contentReference[oaicite:77]{index=77}
• Retriever-Dokumente – Scoring & Interpretation. :contentReference[oaicite:78]{index=78}

---

I) mindnet_appendices_v2.2.md

Zweck & Zielgruppe

• Referenzen, Tabellen, technische Details, die Hauptdokumente nicht überfrachten sollen.

Geplantes Inhaltsverzeichnis

1. Typenreferenz (Auszug aus types.yaml)
   • Tabellenform: Typ, chunk_profile, edge_defaults, retriever_weight
2. Edge-Typen & Bedeutungen
   • belongs_to, references, depends_on, similar_to, related_to, next, prev, …
3. Datenmodelle (JSON-Skizzen)
   • Note, Chunk, Edge-Payload (aktuell implementierter Stand)
4. Relevante ENV-Variablen & Konfigurationen
   • Hash-Settings, COLLECTION_PREFIX, MINDNET_TYPES_FILE, MINDNET_RETRIEVER_CONFIG etc.
5. WP-Übersicht & Status
   • kompakte Tabelle aller WPs mit Status (🟢/🟡) und Verweisen auf relevante Dokumente.
6. Historische Dokumente
   • Verweis auf alte Versionen (mindnet_functional_architecture.md, ältere Playbooks), falls diese nicht vollständig eingearbeitet werden.

Building Blocks

• TYPE_REGISTRY_MANUAL.md – Typen-Referenz. :contentReference[oaicite:84]{index=84}
• chunking_strategy.md – JSON-Beispiele. :contentReference[oaicite:85]{index=85}
• mindnet_technical_architecture.md – Felder & Prioritäten. :contentReference[oaicite:86]{index=86}
• Programmplan – WP-Tabellen.

---

5. Bearbeitungsreihenfolge (Empfehlung)

Aus Sicht der Informationssicherung und Konsistenz ist folgende Reihenfolge sinnvoll:

1. C – mindnet_technical_architecture_v2.2.md

   • Begründung:
     • bildet den aktuellen implementierten Stand von WP02–WP04a am präzisesten ab,
     • ist stark an konkrete Felder, Collections und Skripte gebunden (hier ist der Ist-Stand am eindeutigsten belegbar),
     • ist die Grundlage für Developer Guide, Playbook und Admin Guide.

2. E – mindnet_pipeline_playbook_v2.2.md

   • Konsolidiert Handbuch + Implementation-Playbook + WP04-Dokumente.

3. D – mindnet_knowledge_design_manual_v2.2.md

   • Stellt sicher, dass das Wissensdesign stabil dokumentiert ist, bevor Overview/User Guide entstehen.

4. A – mindnet_overview_v2.2.md

   • Kann sich dann sauber auf die finalisierte fachliche/technische Sicht stützen.

5. F, G, H, I

   • Developer/Admin/User Guides & Appendices, basierend auf den konsolidierten Kern-Dokumenten.

---

6. Nächster konkreter Schritt

Als nächstes finalisieren wir gemäß dieser Reihenfolge das Dokument:

C – mindnet_technical_architecture_v2.2.md

Dabei gehen wir wie folgt vor:

1. Bestehendes mindnet_technical_architecture.md vollständig als Basis übernehmen. :contentReference[oaicite:89]{index=89}
2. Fehlende Details aus chunking_strategy.md, Handbuch.md, TYPE_REGISTRY_MANUAL.md und wp04_retriever_scoring.md integrieren (ohne Informationsverlust).
3. Ist-Stand vs. Roadmap klar kennzeichnen (WP04b–08, WP05–07).

Dieses Vorgehen hält die technische Wahrheit konsistent und liefert eine stabile Basis für alle nachfolgenden Dokumente.