From cb1d1ada8eba035903258cb3c5e09a5f94961368 Mon Sep 17 00:00:00 2001 From: Lars Date: Fri, 30 Jan 2026 12:36:27 +0100 Subject: [PATCH] Update authoring guidelines, knowledge design manual, and Obsidian integration guide for Section Types and Intra-Note-Edges (WP-26) - Incremented version numbers to reflect updates: authoring guidelines to 1.4.0, knowledge design manual to 4.6.0, and Obsidian integration guide to 1.1.0. - Introduced detailed documentation on Section Types and Intra-Note-Edges, including syntax, rules, and examples for implementation. - Enhanced context in the knowledge design manual to include new features related to section types and intra-note edges. - Updated scopes in all relevant documents to reflect the addition of section types and intra-note edges, ensuring comprehensive coverage of the new functionalities. --- .../01_User_Manual/01_authoring_guidelines.md | 24 +- docs/01_User_Manual/01_knowledge_design.md | 255 +++++++++++++++++- .../01_obsidian_integration_guide.md | 89 +++++- 3 files changed, 358 insertions(+), 10 deletions(-) diff --git a/docs/01_User_Manual/01_authoring_guidelines.md b/docs/01_User_Manual/01_authoring_guidelines.md index b05820d..676f198 100644 --- a/docs/01_User_Manual/01_authoring_guidelines.md +++ b/docs/01_User_Manual/01_authoring_guidelines.md @@ -3,9 +3,9 @@ id: 01-authoring-guidelines title: Authoring Guidelines – Handbuch für den Digitalen Zwilling type: principle status: stable -version: 1.3.0 +version: 1.4.0 area: system_documentation -tags: [handbuch, authoring, methodik, obsidian, mindnet, best-practice] +tags: [handbuch, authoring, methodik, obsidian, mindnet, best-practice, section_types, wp26] retriever_weight: 2.0 --- @@ -18,7 +18,7 @@ Dieses Handbuch ist dein primäres Werkzeug, um Wissen so zu strukturieren, dass ## ⚡ Die 6 Goldenen Regeln (TL;DR) 1. **Atomare Gedanken:** Eine Notiz = Ein Thema. Trenne z. B. „Meditation“ von „Mobility“. -2. **Explizite Typen:** Nutze den `type` im Frontmatter (z. B. `insight`, `experience`, `value`), um die mathematische Gewichtung zu steuern. +2. **Explizite Typen:** Nutze den `type` im Frontmatter (z. B. `insight`, `experience`, `value`), um die mathematische Gewichtung zu steuern. **Section Types (WP-26):** Innerhalb einer Note können Abschnitte eigene Types haben (`> [!section] insight`), um präzisere semantische Verarbeitung zu ermöglichen. 3. **H3-Hub-Pairing (NEU):** Nutze H3-Überschriften in Hubs, um spezifische Links und ihre Bedeutung (Edges) in isolierten Chunks für die KI zu fixieren, ohne die Obsidian-Graphen-Logik zu brechen. 4. **Werte & Ziele definieren:** Erstelle für jeden Kernwert eine eigene Notiz (`type: value`). Ohne explizite Maßstäbe kann die Decision Engine nicht in deinem Sinne abwägen. 5. **Emotionales Bridging:** Nutze Begriffe wie „Druck“, „Faszination“ oder „Angst“, um die Empathie-Ebene der KI zu aktivieren. @@ -81,6 +81,13 @@ Nutze das kanonische Vokabular in `[!edge]` Callouts innerhalb der H3-Sektionen: * **`part_of` / `gehört_zu`**: Bindet Details an einen übergeordneten Cluster oder Hub. * **`guides` / `steuert`**: Prinzipien oder Werte, die eine Sektion oder ein Vorhaben leiten. +**Intra-Note-Edges (WP-26):** Für Verbindungen innerhalb derselben Note nutze Block-References: +```markdown +> [!edge] derives +> [[#^block-id]] +``` +Dies erzeugt semantische Verbindungen zwischen Chunks derselben Note (`is_internal: true`). + ### 4.2 Forward-Mapping (Strategische Lücken) Setze bewusst Links auf Dateien, die noch nicht existieren (z. B. `[[Die beste Version meiner selbst]]`). Die KI erkennt diese Lücken und stellt proaktiv Fragen, um diese Felder gemeinsam mit dir zu füllen. @@ -92,6 +99,17 @@ Setze bewusst Links auf Dateien, die noch nicht existieren (z. B. `[[Die beste V **Ziel:** Den „Spiegel“ (Empathy) mit deiner Biografie kalibrieren. * **Struktur:** Kontext (Was ist passiert?), Emotions-Check (Gefühle?), Lektion (Was gelernt?). * **Deep-Edge:** Verknüpfe es immer mit einer Rolle: `[[rel:supports Meine Rollenlandkarte 2025#Vater]]`. +* **Section Types (WP-26):** Nutze unterschiedliche Section-Types für verschiedene Abschnitte: + ```markdown + ## Situation ^sit + > [!section] experience + + ## Reflexion ^ref + > [!section] insight + > [!edge] derives + > [[#^sit]] + ``` + Dies ermöglicht präzisere semantische Verarbeitung und Intra-Note-Verbindungen. ### 5.2 Eine Beobachtung festhalten (`type: insight`) **Ziel:** Den „Berater“ (Decision) mit Mustern versorgen. diff --git a/docs/01_User_Manual/01_knowledge_design.md b/docs/01_User_Manual/01_knowledge_design.md index 9abc8b2..02519b3 100644 --- a/docs/01_User_Manual/01_knowledge_design.md +++ b/docs/01_User_Manual/01_knowledge_design.md @@ -1,10 +1,10 @@ --- doc_type: user_manual audience: user, author -scope: vault, markdown, schema, agentic_validation, note_scope +scope: vault, markdown, schema, agentic_validation, note_scope, section_types, intra_note_edges status: active -version: 4.5.8 -context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren. Inkludiert WP-24c Phase 3 Agentic Edge Validation, automatische Spiegelkanten und Note-Scope Zonen." +version: 4.6.0 +context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren. Inkludiert WP-24c Phase 3 Agentic Edge Validation, automatische Spiegelkanten, Note-Scope Zonen und WP-26 Section Types mit Intra-Note-Edges." --- # Knowledge Design Manual @@ -198,6 +198,169 @@ Damit dein System sauber bleibt, beachte diese Regeln: --- +## 4. Section Types & Intra-Note-Edges (WP-26) [NEU] + +### 4.0 Übersicht: Section Types + +**Section Types** ermöglichen es, innerhalb einer Note unterschiedliche Typen für verschiedene Abschnitte zu definieren. Dies erlaubt präzisere semantische Verarbeitung und Intra-Note-Verbindungen zwischen Chunks. + +**Kernkonzept:** +- Eine Note hat einen **Note-Type** (im Frontmatter: `type: experience`) +- Abschnitte innerhalb der Note können einen eigenen **Section-Type** haben (z.B. `insight`, `decision`) +- Der **effektive Typ** eines Chunks ist: `section_type` falls vorhanden, sonst `note_type` +- Section Types ermöglichen **Intra-Note-Edges** – semantische Verbindungen zwischen Chunks derselben Note + +### 4.0.1 Section-Type-Deklaration + +**Syntax:** +```markdown +## Überschrift ^block-id +> [!section] type-name +``` + +**Beispiel:** +```markdown +--- +type: experience +title: Konflikt im Team-Meeting +--- + +# Konflikt im Team-Meeting + +## Situation ^sit +> [!section] experience + +Am 15. Januar kam es zu einer Eskalation... + +## Reflexion ^ref +> [!section] insight + +Diese Erfahrung zeigt mir, dass... + +## Nächste Schritte ^next +> [!section] decision + +Ich werde in Zukunft früher eingreifen. +``` + +**Regeln:** +- Der Section-Type gilt ab der Überschrift bis zur nächsten Überschrift **gleicher oder höherer Ebene** +- Das `[!section]`-Callout kann **an beliebiger Stelle** innerhalb des Abschnitts stehen (muss nicht direkt unter der Überschrift sein) +- Das `[!section]`-Callout ist **unabhängig** von `[!edge]`-Callouts und kann separat platziert werden +- Bei Fehlen eines `[!section]`-Callouts gilt der Note-Type als Fallback +- Valide Section-Types müssen in `types.yaml` definiert sein + +**Automatische Section-Erkennung:** +Sobald eine Section auf einer bestimmten Überschriften-Ebene eingeführt wurde (z.B. H2), beginnt bei **jeder weiteren Überschrift auf dieser Ebene automatisch eine neue Section** – auch ohne explizites `[!section]`-Callout. + +**Beispiel:** +```markdown +## Situation ^sit +> [!section] experience +Text A... → type = "experience" (explizit) + +## Reflexion ^ref + +Text B... → type = "experience" (note_type Fallback) + → ABER: Neue Section erkannt, neuer Chunk! + +## Learnings ^learn +> [!section] insight +Text C... → type = "insight" (explizit) +``` + +**Body-Section:** +Textblöcke, die **vor dem ersten `[!section]`-Callout** stehen, erhalten: +- `section: "body"` +- `type: note_type` (Fallback) +- `section_type: None` + +### 4.0.2 Intra-Note-Edges (Verbindungen innerhalb einer Note) + +**Block-References als Link-Format:** + +Das bevorzugte Format für Intra-Note-Links: +```markdown +> [!edge] derives +> [[#^block-id]] +``` + +**Fallback (mit Einschränkungen):** +```markdown +> [!edge] derives +> [[#Section-Name]] +``` + +**Vollständiges Beispiel:** +```markdown +## Situation ^sit +> [!section] experience + +Die Geschichte... + +## Reflexion ^ref +> [!section] insight +> [!edge] derives +> [[#^sit]] + +Was ich daraus lerne... +``` + +**Ergebnis:** +- Chunk der Reflexion (`#ref`) erhält eine `derives`-Kante zum Chunk der Situation (`#sit`) +- Beide Chunks sind in derselben Note → `is_internal: true` +- Scope ist `chunk` (nicht `note`) + +**Automatische Backlinks:** +Für alle Intra-Note-Edges werden automatisch inverse Backlinks erzeugt: +- Forward-Edge: `#ref --[derives]--> #sit` +- Backlink: `#sit --[derived_from]--> #ref` (automatisch) + +**Default-Edges aus graph_schema.md:** +Wenn keine expliziten Intra-Note-Edges definiert sind, aber Section-Types vorhanden: +- System ermittelt Source-Type und Target-Type (benachbarte Sektionen) +- Lookup in `graph_schema.md` via `get_topology_info(source_type, target_type)` +- Erster Eintrag aus `typical` wird als Default-Edge-Type verwendet + +**Beispiel:** +```markdown +## Situation ^sit +> [!section] experience + +## Reflexion ^ref +> [!section] insight + +``` + +**Ergebnis:** Automatische Edge `experience --[resulted_in]--> insight` (aus Schema) + +### 4.0.3 Effektiver Typ & Retrieval + +**Kernregel:** Der **Section-Type (sofern vorhanden) hat immer Vorrang** vor dem `note_type` für: +- Vektor-Embedding (Suche) +- `retriever_weight` Lookup +- Type-Filter in Queries +- Graph-Expansion + +**Beispiel:** +Ein Chunk mit `type: "insight"` und `note_type: "experience"` erhält: +- `retriever_weight: 1.20` (aus `types.yaml` für `insight`, nicht `experience`) +- Wird bei `filter: {type: "insight"}` gefunden +- Wird bei `filter: {note_type: "experience"}` ebenfalls gefunden + +**Chunk-Payload-Struktur:** +```python +{ + "type": "insight", # Effektiver Typ (section_type || note_type) + "note_type": "experience", # Ursprünglicher Note-Typ (immer vorhanden) + "section": "Reflexion", + "section_type": "insight", # Expliziter Section-Type (optional) + ... +} +``` + +--- + ## 4. Edges & Verlinkung Mindnet versteht Zusammenhänge durch Kanten. @@ -214,6 +377,15 @@ Du kannst auch auf spezifische Abschnitte innerhalb einer Note verlinken: Das System trennt automatisch den Note-Namen (`Mein Leitbild`) vom Abschnitts-Namen (`P3 – Disziplin`), sodass mehrere Links zur gleichen Note möglich sind, wenn sie auf verschiedene Abschnitte zeigen. +**Intra-Note-Links mit Block-IDs (WP-26):** +Für Verbindungen **innerhalb derselben Note** nutze Block-References: +```markdown +> [!edge] derives +> [[#^block-id]] +``` + +Dies erzeugt eine Intra-Note-Edge mit `is_internal: true` und `scope: "chunk"`. + **Gültige Relationen:** * `depends_on`: Hängt ab von / Benötigt. * `blocks`: Blockiert oder gefährdet (z.B. Risiko -> Projekt). @@ -235,6 +407,24 @@ Für Zusammenfassungen am Ende einer Notiz, oder eines Absatzes: **Multi-Line Support (v2.9.1):** Callout-Blocks mit mehreren Zeilen werden korrekt verarbeitet. Das System erkennt automatisch, wenn mehrere Links im gleichen Callout-Block stehen, und erstellt für jeden Link eine separate Kante (auch bei Deep-Links zu verschiedenen Sections). +**Verschachtelte Edge-Callouts in Containern (WP-26):** +Für übersichtliche Gruppierung von Edges kannst du verschachtelte Callouts nutzen: + +```markdown +> [!abstract] Semantic Edges +>> [!edge] derived_from +>> [[Wikilink#Abschnitt]] +> +>> [!edge] solves +>> [[Wikilink2]] +``` + +**Regeln:** +- Container-Callouts wie `[!abstract]` werden als Gruppierung erkannt, aber nicht semantisch verarbeitet +- Eingebettete `>> [!edge]` Callouts werden korrekt extrahiert +- Die Einrückungsebene (Anzahl `>`) bestimmt die Zugehörigkeit zum Block +- Leere Zeilen innerhalb des Containers (mit `>`) beenden den Edge-Block nicht + **Format-agnostische De-Duplizierung:** Wenn Kanten bereits via `[!edge]` Callout vorhanden sind, werden sie nicht mehrfach injiziert. Das System erkennt vorhandene Kanten unabhängig vom Format (Inline, Callout, Wikilink). @@ -452,6 +642,65 @@ Wir haben uns für Qdrant entschieden. Wir haben auch [[rel:similar_to Pinecone]] und [[rel:similar_to Weaviate]] betrachtet. ``` +### 6.3 Beispiel: Section Types & Intra-Note-Edges (WP-26) +Eine Erfahrungs-Notiz mit unterschiedlichen Section-Types und Intra-Note-Verbindungen: + +```markdown +--- +id: erlebnis-konflikt-team +title: Konflikt im Team-Meeting +type: experience +tags: [team, konflikt, learning] +--- + +# Konflikt im Team-Meeting + +## Situation ^sit +> [!section] experience + +Am 15. Januar 2026 kam es im Sprint-Review zu einer Eskalation... + +## Meine Reaktion ^react +> [!section] experience +> [!edge] followed_by +> [[#^sit]] + +Ich habe versucht zu deeskalieren, aber... + +## Reflexion ^ref +> [!section] insight + +Diese Erfahrung zeigt mir, dass ich in Konfliktsituationen... + +> [!abstract] Semantic Edges +>> [!edge] derives +>> [[#^sit]] +>> [[#^react]] + +## Nächste Schritte ^next +> [!section] decision + +Ich werde in Zukunft: +1. Früher eingreifen +2. Neutrale Sprache verwenden + +> [!edge] caused_by +> [[#^ref]] +``` + +**Ergebnis:** +- **4 Chunks** mit unterschiedlichen Types: + - `#sit`: `type: experience` (explizit) + - `#react`: `type: experience` (explizit) + - `#ref`: `type: insight` (explizit, überschreibt `note_type`) + - `#next`: `type: decision` (explizit, überschreibt `note_type`) +- **Intra-Note-Edges:** + - `#react --[followed_by]--> #sit` + - `#ref --[derives]--> #sit` + - `#ref --[derives]--> #react` + - `#next --[caused_by]--> #ref` +- Alle Edges haben `is_internal: true` und `scope: "chunk"` + --- ## 7. Virtual Schema Layer diff --git a/docs/01_User_Manual/01_obsidian_integration_guide.md b/docs/01_User_Manual/01_obsidian_integration_guide.md index c046a73..06b6039 100644 --- a/docs/01_User_Manual/01_obsidian_integration_guide.md +++ b/docs/01_User_Manual/01_obsidian_integration_guide.md @@ -1,10 +1,10 @@ --- doc_type: technical_reference audience: developer, power_user -scope: obsidian, scripts, workflow +scope: obsidian, scripts, workflow, section_types, intra_note_edges status: active -version: 1.0.0 -context: "Setup und Dokumentation der Obsidian-Integration für Mindnet v2.9." +version: 1.1.0 +context: "Setup und Dokumentation der Obsidian-Integration für Mindnet v2.9. Inkludiert WP-26 Section Types und Intra-Note-Edges." --- # Obsidian Integration Guide @@ -67,6 +67,87 @@ Damit die Skripte funktionieren, müssen folgende Pfade im Vault existieren: --- -## 5. Wartung & Updates +## 5. Section Types & Intra-Note-Edges (WP-26) + +### 5.1 Section-Type-Syntax + +Das Backend unterstützt nun **Section Types** innerhalb von Notes: + +**Format:** +```markdown +## Überschrift ^block-id +> [!section] type-name +``` + +**Beispiel:** +```markdown +--- +type: experience +--- + +# Meine Erfahrung + +## Situation ^sit +> [!section] experience + +Die Geschichte... + +## Reflexion ^ref +> [!section] insight +> [!edge] derives +> [[#^sit]] + +Was ich daraus lerne... +``` + +**Wichtige Regeln:** +- Das `[!section]`-Callout kann an beliebiger Stelle innerhalb des Abschnitts stehen +- Der Section-Type gilt bis zur nächsten Überschrift gleicher oder höherer Ebene +- Bei Fehlen eines `[!section]`-Callouts gilt der Note-Type als Fallback +- Valide Section-Types müssen in `types.yaml` definiert sein + +### 5.2 Intra-Note-Edges mit Block-References + +Für Verbindungen **innerhalb derselben Note** nutze Block-References: + +**Bevorzugtes Format:** +```markdown +> [!edge] derives +> [[#^block-id]] +``` + +**Fallback:** +```markdown +> [!edge] derives +> [[#Section-Name]] +``` + +**Verschachtelte Edge-Callouts:** +Für übersichtliche Gruppierung kannst du verschachtelte Callouts nutzen: + +```markdown +> [!abstract] Semantic Edges +>> [!edge] derived_from +>> [[#^sit]] +>> [[#^react]] +> +>> [!edge] supports +>> [[Externe Note]] +``` + +### 5.3 Automatische Features + +**Automatische Section-Erkennung:** +Sobald eine Section auf einer bestimmten Überschriften-Ebene eingeführt wurde, beginnt bei jeder weiteren Überschrift auf dieser Ebene automatisch eine neue Section – auch ohne explizites `[!section]`-Callout. + +**Automatische Backlinks:** +Für alle Intra-Note-Edges werden automatisch inverse Backlinks erzeugt: +- Forward-Edge: `#ref --[derives]--> #sit` +- Backlink: `#sit --[derived_from]--> #ref` (automatisch) + +**Default-Edges aus graph_schema.md:** +Wenn keine expliziten Intra-Note-Edges definiert sind, aber Section-Types vorhanden, werden automatisch Default-Edges aus dem Graph-Schema generiert. + +## 6. Wartung & Updates Bei Änderungen an den Notiz-Typen in der `types.yaml` müssen die entsprechenden Markdown-Vorlagen im Ordner `creation` manuell synchronisiert werden, um die Konsistenz zwischen Obsidian und dem Backend zu wahren. \ No newline at end of file