mindnet_obsidian/docs/Interview_Config_Guide.md

Interview Config Guide - Vollständige Anleitung für interview_config.yaml

Version: 1.0.0
Stand: 2025-01-25
Zielgruppe: Administratoren, GenAI-Assistenten, Plugin-Entwickler
Zweck: Vollständige Dokumentation zur Erstellung von Interview-Profilen für verschiedene Note-Typen

---

Inhaltsverzeichnis

1. Überblick
2. Grundstruktur
3. Root-Level Felder
4. Profile-Definition
5. Step-Typen
6. WP-26 Features (Section Types & Block-IDs)
7. Beispiele für verschiedene Note-Typen
8. Best Practices & Patterns
9. Validierung & Fehlerbehandlung

---

Überblick

Die interview_config.yaml definiert Interview-Profile für die strukturierte Erstellung von Notes im Obsidian Vault. Jedes Profil beschreibt einen Wizard-Flow mit mehreren Steps, die nacheinander durchlaufen werden, um eine Note zu erstellen.

Wichtige Konzepte

• Profile: Ein Interview-Profil entspricht einem Note-Typ (z.B. experience, insight, decision)
• Steps: Einzelne Schritte im Interview-Wizard (z.B. Text-Eingabe, Frontmatter-Feld, Loop)
• Loops: Wiederholbare Steps für Listen von Items
• Section Types (WP-26): Typisierung von Abschnitten innerhalb einer Note
• Block-IDs (WP-26): Eindeutige Referenzpunkte für Intra-Note-Verlinkungen

---

Grundstruktur

version: 3

frontmatter_whitelist:
  - id
  - title
  - type
  - status
  # ... weitere erlaubte Frontmatter-Keys

ui_defaults:
  modal:
    width: "clamp(720px, 88vw, 1100px)"
    height: "clamp(640px, 86vh, 920px)"
  editor:
    preview_toggle: true
    toolbar: true
    full_width_inputs: true

profiles:
  - key: profile_key
    label: "Anzeige-Name"
    note_type: experience
    # ... Profile-Definition

---

Root-Level Felder

version (string, optional)

Standard: 3

Die Versionsnummer der Config-Datei. Aktuell wird Version 3 verwendet.

frontmatter_whitelist (array of strings, optional)

Liste von Frontmatter-Keys, die im Wizard bearbeitet werden können.

Standard-Keys (immer verfügbar):

• id
• title
• type
• status
• retriever_weight
• chunking_profile
• tags
• aliases
• created
• interview_profile

Beispiel:

frontmatter_whitelist:
  - custom_field
  - priority

ui_defaults (object, optional)

Standard-UI-Einstellungen für den Interview-Wizard.

Felder:

• modal.width (string): CSS-Width für das Modal
• modal.height (string): CSS-Height für das Modal
• editor.preview_toggle (boolean): Preview-Toggle anzeigen
• editor.toolbar (boolean): Toolbar anzeigen
• editor.full_width_inputs (boolean): Volle Breite für Inputs

profiles (array, required)

Liste von Interview-Profilen. Siehe Profile-Definition.

---

Profile-Definition

Jedes Profil definiert einen vollständigen Interview-Wizard für einen Note-Typ.

Pflichtfelder

• key (string, required): Eindeutiger Schlüssel für das Profil (z.B. experience_cluster)
• label (string, required): Anzeige-Name im UI
• note_type (string, required): Note-Typ (muss mit types.yaml übereinstimmen, z.B. experience, insight, decision)
• steps (array, required): Liste von Steps (mindestens ein Step)

Optionale Felder

• group (string, optional): Gruppierung für UI (z.B. experience, insight)
• defaults (object, optional): Standardwerte für Frontmatter
  • status (string): Standard-Status (z.B. active, stable)
  • folder (string): Standard-Ordner für neue Notes
  • chunking_profile (string): Standard-Chunking-Profil
  • retriever_weight (number): Standard-Retriever-Weight
  • tags (array of strings): Standard-Tags
• edging (object, optional): Semantic Mapping Konfiguration
  • mode (string): "none" | "post_run" | "inline_micro" | "both" (Standard: "none")
  • wrapperCalloutType (string, optional): Override für Wrapper-Callout-Typ
  • wrapperTitle (string, optional): Override für Wrapper-Titel
  • wrapperFolded (boolean, optional): Override für Wrapper-Folded-State

Beispiel:

profiles:
  - key: experience_basic
    group: experience
    label: "Erfahrung (Basis)"
    note_type: experience
    defaults:
      status: active
      folder: "03_experience"
      chunking_profile: timeline
    edging:
      mode: both
    steps:
      # ... Steps

---

Step-Typen

1. capture_frontmatter - Frontmatter-Feld erfassen

Erfasst ein einzelnes Frontmatter-Feld.

Felder:

• id (string, required): Eindeutige Step-ID
• kind (string, required): "capture_frontmatter"
• field (string, required): Frontmatter-Feld-Name (muss in frontmatter_whitelist sein)
• label (string, optional): Anzeige-Name (Standard: field)
• required (boolean, optional): Ob erforderlich (Standard: false)
• prompt (string, optional): Prompt-Text für den Benutzer
• input.kind (string, optional): Input-Typ (text_line, number, select, etc.)
• input.min (number, optional): Min-Wert für number
• input.max (number, optional): Max-Wert für number
• input.step (number, optional): Step-Wert für number
• input.options (array, optional): Optionen für select

Beispiel:

- id: title
  kind: capture_frontmatter
  field: title
  label: "Titel"
  required: true
  prompt: "Gib einen Titel für die Note ein"

- id: retriever_weight
  kind: capture_frontmatter
  field: retriever_weight
  label: "Retriever Weight"
  required: false
  input:
    kind: number
    min: -3
    max: 3
    step: 1

2. capture_text - Mehrzeiligen Text erfassen

Erfasst mehrzeiligen Text und erzeugt eine Section in der Note.

Felder:

• id (string, required): Eindeutige Step-ID
• kind (string, required): "capture_text"
• label (string, optional): Anzeige-Name
• required (boolean, optional): Ob erforderlich (Standard: false)
• prompt (string, optional): Prompt-Text für den Benutzer
• section (string, optional): Markdown-Section-Header (z.B. "## 📖 Kontext")
  • Wenn leer (""), wird kein Section-Header erzeugt (z.B. in Loops)
• WP-26 Felder: Siehe WP-26 Features

Beispiel:

- id: context
  kind: capture_text
  section: "## 📖 Kontext"
  label: "Kontext"
  required: true
  prompt: "Beschreibe den Kontext der Erfahrung"
  section_type: experience
  generate_block_id: true

3. capture_text_line - Einzeiligen Text erfassen

Erfasst einzeiligen Text, optional mit Heading-Level.

Felder:

• id (string, required): Eindeutige Step-ID
• kind (string, required): "capture_text_line"
• label (string, optional): Anzeige-Name
• required (boolean, optional): Ob erforderlich (Standard: false)
• prompt (string, optional): Prompt-Text für den Benutzer
• heading_level.enabled (boolean, optional): Heading-Level-Selector anzeigen (Standard: false)
• heading_level.default (number, optional): Standard-Heading-Level 1-6 (Standard: 2)
• WP-26 Felder: Siehe WP-26 Features

Beispiel:

- id: subtitle
  kind: capture_text_line
  label: "Untertitel"
  heading_level:
    enabled: true
    default: 1
  prompt: "Kurzer Untertitel"
  section_type: experience
  generate_block_id: true

4. loop - Wiederholbare Steps

Erzeugt eine Liste von Items, die durch wiederholte Ausführung der Sub-Steps erzeugt werden.

Felder:

• id (string, required): Eindeutige Step-ID
• kind (string, required): "loop"
• label (string, optional): Anzeige-Name für die Loop
• item_label (string, optional): Anzeige-Name für einzelne Items (z.B. "Erlebnis")
• min_items (number, optional): Minimale Anzahl Items (Standard: 0)
• max_items (number, optional): Maximale Anzahl Items (kein Limit, wenn nicht gesetzt)
• steps (array, required): Liste von Sub-Steps (werden für jedes Item ausgeführt)
• output.join (string, optional): String zum Verbinden der Items (Standard: "\n\n")
• ui.mode (string, optional): UI-Modus (subwizard | inline, Standard: inline)
• ui.commit (string, optional): Commit-Modus (explicit_add | on_next, Standard: explicit_add)
• ui.allow_edit (boolean, optional): Bearbeitung erlauben (Standard: false)
• ui.allow_delete (boolean, optional): Löschen erlauben (Standard: false)
• ui.allow_reorder (boolean, optional): Neuordnen erlauben (Standard: false)
• ui.show_item_overview (boolean, optional): Item-Übersicht anzeigen (Standard: false)

Beispiel:

- id: actions
  kind: loop
  label: "Handlungen"
  item_label: "Handlung"
  min_items: 1
  steps:
    - id: action_heading
      kind: capture_text_line
      label: "Handlungsüberschrift"
      required: true
      heading_level:
        enabled: true
        default: 3
      section_type: decision
      generate_block_id: true
    - id: action_description
      kind: capture_text
      section: ""
      label: "Beschreibung"
      required: true

Verschachtelte Loops:

- id: groups
  kind: loop
  label: "Erlebnis-Gruppen"
  steps:
    - id: group_heading
      kind: capture_text_line
      label: "Überschrift"
    - id: entries
      kind: loop
      label: "Einträge"
      steps:
        - id: entry
          kind: capture_text_line
          label: "Listeneintrag"

5. review - Review & Apply Step

Zeigt eine Vorschau der generierten Note und ermöglicht abschließende Checks.

Felder:

• id (string, required): Eindeutige Step-ID
• kind (string, required): "review"
• label (string, optional): Anzeige-Name (Standard: "Review & Apply")
• checks (array of strings, optional): Liste von Checks
  • lint_current_note: Lint-Check für die generierte Note
  • missing_targets: Prüft auf fehlende Link-Targets
  • missing_frontmatter_id: Prüft auf fehlende Frontmatter-ID

Beispiel:

- id: review
  kind: review
  label: "Review & Apply"
  checks:
    - lint_current_note
    - missing_targets
    - missing_frontmatter_id

6. instruction - Anweisung anzeigen

Zeigt eine reine Anweisung ohne Input.

Felder:

• id (string, required): Eindeutige Step-ID
• kind (string, required): "instruction"
• label (string, optional): Anzeige-Name
• content (string, required): Markdown-Inhalt der Anweisung

Beispiel:

- id: intro
  kind: instruction
  label: "Einführung"
  content: |
    # Willkommen zum Interview
    
    Dieses Interview hilft dir, eine strukturierte Note zu erstellen.    

7. llm_dialog - LLM-Dialog (experimentell)

Öffnet einen LLM-Dialog für Text-Generierung oder -Verdichtung.

Felder:

• id (string, required): Eindeutige Step-ID
• kind (string, required): "llm_dialog"
• label (string, optional): Anzeige-Name
• mode (string, optional): "manual" | "auto" (Standard: "manual")
• prompt_template (string, required): Prompt-Template für den LLM
• output_target.kind (string, required): Output-Ziel (section_append | replace)
• output_target.section (string, optional): Section für section_append

Beispiel:

- id: llm_refine
  kind: llm_dialog
  label: "LLM – Verdichtung"
  mode: manual
  prompt_template: |
    Verdichte die bisherigen Inhalte zu 3-5 Bulletpoints.
    Erfinde keine Fakten.    
  output_target:
    kind: section_append
    section: "## 🧠 Verdichtung (LLM Vorschlag)"

8. entity_picker - Entity-Auswahl (experimentell)

Ermöglicht die Auswahl einer bestehenden Note aus dem Vault.

Felder:

• id (string, required): Eindeutige Step-ID
• kind (string, required): "entity_picker"
• label (string, optional): Anzeige-Name
• prompt (string, optional): Prompt-Text
• required (boolean, optional): Ob erforderlich (Standard: false)
• labelField (string, optional): Feld-Key für Wikilink-Label

---

WP-26 Features (Section Types & Block-IDs)

Wichtig: Diese Features sind nur für capture_text und capture_text_line Steps verfügbar.

section_type (string, optional)

Definiert den Section-Type für diese Section. Überschreibt den note_type für diese Section.

Verwendung:

• Für Edge-Type-Vorschläge basierend auf graph_schema.md
• Für Type-Boost-Scoring im Retriever
• Für Agentic Validation (Phase 3)

Beispiel:

- id: insight
  kind: capture_text
  section: "## 💡 Einsicht"
  section_type: insight  # Typ-Wechsel: experience -> insight

Fallback-Logik:

• Wenn section_type nicht gesetzt ist, wird der note_type des Profils verwendet
• Bei verschachtelten Sections wird der Section-Type der übergeordneten Section verwendet (basierend auf Heading-Level)

block_id (string, optional)

Definiert eine explizite Block-ID für diese Section. Die Block-ID wird als ^block-id am Ende der Überschrift erzeugt.

Beispiel:

- id: situation
  kind: capture_text
  section: "## ⚡ Situation"
  block_id: "sit"  # Erzeugt: ## ⚡ Situation ^sit

Wichtig: Block-IDs müssen eindeutig sein. In Loops werden automatisch Nummerierungen angehängt (z.B. action_heading-1, action_heading-2).

generate_block_id (boolean, optional)

Wenn true, wird automatisch eine Block-ID aus der Step-ID generiert (slugified).

Beispiel:

- id: context
  kind: capture_text
  section: "## 📖 Kontext"
  generate_block_id: true  # Erzeugt: ## 📖 Kontext ^context

Regeln:

• Wenn sowohl block_id als auch generate_block_id: true gesetzt sind, hat block_id Priorität
• In Loops wird automatisch eine Nummerierung angehängt (z.B. context-1, context-2)

references (array, optional)

Definiert explizite Referenzen zu vorherigen Sections (Block-IDs).

Struktur:

references:
  - block_id: <block_id_der_referenzierten_section>
    edge_type: <optional_vorgeschlagener_edge_type>

Beispiel:

- id: situation
  kind: capture_text
  section: "## ⚡ Situation"
  section_type: experience
  block_id: "sit"
  references:
    - block_id: context
      edge_type: derived_from  # Explizite Referenz zu vorheriger Section

Verhalten:

• Referenzen werden als Intra-Note-Edges erzeugt (is_internal: true)
• Der edge_type wird als Vorschlag verwendet (kann im SectionEdgesOverviewModal geändert werden)
• Wenn kein edge_type angegeben ist, wird ein Typ aus graph_schema.md vorgeschlagen
• Automatische Rückwärts-Edges werden in der Ziel-Section erzeugt (basierend auf dem inversen Edge-Type)

Wichtig: block_id muss auf eine vorherige Section verweisen (nicht auf zukünftige Sections).

---

Beispiele für verschiedene Note-Typen

Experience (Erfahrung)

- key: experience_single
  group: experience
  label: "Experience – Einzelereignis"
  note_type: experience
  defaults:
    status: active
    chunking_profile: timeline
  edging:
    mode: both
  steps:
    - id: title
      kind: capture_frontmatter
      field: title
      label: "Titel"
      required: true

    - id: context
      kind: capture_text
      section: "## 📖 Kontext"
      label: "Kontext"
      required: true
      prompt: "In welchem Rahmen ist es passiert?"
      section_type: experience
      generate_block_id: true

    - id: trigger
      kind: capture_text
      section: "## ⚡ Auslöser"
      label: "Auslöser"
      required: false
      prompt: "Was hat es ausgelöst?"
      section_type: experience
      generate_block_id: true
      references:
        - block_id: context
          edge_type: derived_from

    - id: transformation
      kind: capture_text
      section: "## 🧠 Innere Transformation"
      label: "Innere Transformation"
      required: false
      prompt: "Was hat sich innerlich verändert?"
      section_type: insight  # Typ-Wechsel
      generate_block_id: true

    - id: review
      kind: review
      label: "Review & Apply"
      checks:
        - lint_current_note
        - missing_targets

Insight (Einsicht)

- key: insight_basic
  group: insight
  label: "Insight – Basis"
  note_type: insight
  defaults:
    status: active
    folder: "04_insight"
  edging:
    mode: both
  steps:
    - id: title
      kind: capture_frontmatter
      field: title
      label: "Titel"
      required: true

    - id: insight
      kind: capture_text
      section: "## 💡 Einsicht"
      label: "Einsicht"
      required: true
      prompt: "Beschreibe die Einsicht"
      section_type: insight
      generate_block_id: true

    - id: source
      kind: capture_text
      section: "## 📚 Quelle"
      label: "Quelle"
      required: false
      prompt: "Woher stammt diese Einsicht?"
      section_type: insight
      generate_block_id: true
      references:
        - block_id: insight
          edge_type: source_of

    - id: application
      kind: capture_text
      section: "## 🎯 Anwendung"
      label: "Anwendung"
      required: false
      prompt: "Wie wird diese Einsicht angewendet?"
      section_type: decision  # Typ-Wechsel
      generate_block_id: true
      references:
        - block_id: insight
          edge_type: foundation_for

    - id: review
      kind: review
      label: "Review & Apply"
      checks:
        - lint_current_note

Decision (Entscheidung)

- key: decision_basic
  group: decision
  label: "Decision – Basis"
  note_type: decision
  defaults:
    status: active
    folder: "05_decision"
  edging:
    mode: both
  steps:
    - id: title
      kind: capture_frontmatter
      field: title
      label: "Titel"
      required: true

    - id: context
      kind: capture_text
      section: "## 📖 Kontext"
      label: "Kontext"
      required: true
      prompt: "In welchem Kontext wurde die Entscheidung getroffen?"
      section_type: experience
      generate_block_id: true

    - id: options
      kind: loop
      label: "Optionen"
      item_label: "Option"
      min_items: 2
      steps:
        - id: option_text
          kind: capture_text
          section: ""
          label: "Option"
          required: true
          prompt: "Beschreibe eine Option"

    - id: decision
      kind: capture_text
      section: "## 🎯 Entscheidung"
      label: "Entscheidung"
      required: true
      prompt: "Welche Entscheidung wurde getroffen?"
      section_type: decision
      generate_block_id: true
      references:
        - block_id: context
          edge_type: derived_from

    - id: rationale
      kind: capture_text
      section: "## 🧠 Begründung"
      label: "Begründung"
      required: false
      prompt: "Warum wurde diese Entscheidung getroffen?"
      section_type: insight
      generate_block_id: true
      references:
        - block_id: decision
          edge_type: based_on

    - id: review
      kind: review
      label: "Review & Apply"
      checks:
        - lint_current_note
        - missing_targets

Principle (Prinzip)

- key: principle_basic
  group: principle
  label: "Principle – Basis"
  note_type: principle
  defaults:
    status: stable
    chunking_profile: principle_dense
    retriever_weight: 2
  steps:
    - id: title
      kind: capture_frontmatter
      field: title
      label: "Titel"
      required: true

    - id: statement
      kind: capture_text
      section: "## 🧭 Prinzip"
      label: "Prinzip"
      required: true
      prompt: "Formuliere das Prinzip als klaren Satz."
      section_type: principle
      generate_block_id: true

    - id: retriever_weight
      kind: capture_frontmatter
      field: retriever_weight
      label: "Retriever Weight"
      required: false
      input:
        kind: number
        min: -3
        max: 3
        step: 1

    - id: review
      kind: review
      label: "Review & Apply"
      checks:
        - lint_current_note

---

Best Practices & Patterns

1. Section-Type-Wechsel dokumentieren

Wenn ein Section-Type-Wechsel stattfindet, sollte dies im Kommentar dokumentiert werden:

- id: transformation
  kind: capture_text
  section: "## 🧠 Innere Transformation"
  section_type: insight  # Typ-Wechsel: experience -> insight
  generate_block_id: true

2. Block-IDs konsistent benennen

• Verwende kurze, aussagekräftige Block-IDs (z.B. sit, ctx, ins)
• In Loops werden automatisch Nummerierungen angehängt
• Vermeide kollidierende Block-IDs innerhalb eines Profils

3. Referenzen zu vorherigen Sections

• Referenzen müssen auf vorherige Sections verweisen (nicht zukünftige)
• Verwende explizite edge_type-Vorschläge, wenn die Beziehung klar ist
• Lasse edge_type weg, wenn das System aus graph_schema.md vorschlagen soll

4. Loops für Listen verwenden

• Verwende loop für wiederholbare Items (z.B. Handlungen, Optionen, Erlebnisse)
• Setze min_items für erforderliche Listen
• Verwende section: "" für Steps innerhalb von Loops, die keine eigene Section erzeugen sollen

5. Review-Step immer am Ende

• Jedes Profil sollte mit einem review Step enden
• Aktiviere relevante Checks (lint_current_note, missing_targets, etc.)

6. Edging-Mode konfigurieren

• mode: "both" für vollständige Edge-Unterstützung (inline + post-run)
• mode: "inline_micro" für nur Inline-Edge-Vorschläge
• mode: "post_run" für nur Post-Run-Edge-Abfrage
• mode: "none" für keine Edge-Unterstützung

7. Frontmatter-Felder dokumentieren

• Dokumentiere Custom-Frontmatter-Felder in frontmatter_whitelist
• Verwende sinnvolle Defaults in defaults für bessere UX

---

Validierung & Fehlerbehandlung

YAML-Syntax-Fehler

• Syntax-Fehler werden beim Laden erkannt und geloggt
• Last-Known-Good: Letzte gültige Config wird bei Fehlern verwendet
• Warnings: Ungültige Felder werden als Warnings geloggt, nicht als Fehler

Step-Validierung

• Fehlende Pflichtfelder: Werden als Fehler erkannt
• Ungültige Step-Kinds: Werden als Warnings geloggt
• Ungültige Block-ID-Referenzen: Werden zur Laufzeit erkannt (keine Validierung zur Config-Zeit)

Live-Reload

• Debounced: 200ms Delay für Performance
• Automatisch: Bei Dateiänderungen
• Manuell: Über Commands möglich

---

GenAI-Prompt-Template

Wenn du ein GenAI-Assistent bist und ein neues Interview-Profil erstellen sollst, verwende folgendes Template:

Erstelle ein Interview-Profil für den Note-Typ "{note_type}" mit folgenden Anforderungen:

1. **Profil-Informationen:**
   - Key: {profile_key}
   - Label: {display_name}
   - Group: {group}
   - Note-Type: {note_type}

2. **Default-Werte:**
   - Status: {status}
   - Folder: {folder}
   - Chunking-Profile: {chunking_profile} (optional)
   - Retriever-Weight: {retriever_weight} (optional)

3. **Steps:**
   {step_descriptions}

4. **WP-26 Features:**
   - Section-Types: {section_types}
   - Block-IDs: {block_ids}
   - Referenzen: {references}

5. **Edging:**
   - Mode: {edging_mode}

6. **Review:**
   - Checks: {review_checks}

Nutze die Beispiele aus der Dokumentation als Vorlage und stelle sicher, dass:
- Alle Pflichtfelder gesetzt sind
- Block-IDs eindeutig sind
- Referenzen auf vorherige Sections verweisen
- Section-Types konsistent mit graph_schema.md sind
- Ein Review-Step am Ende steht

---

Zusammenfassung

Die interview_config.yaml ist eine mächtige Konfigurationsdatei für die strukturierte Erstellung von Notes. Mit WP-26 Features können Sections typisiert und referenziert werden, was zu besseren Edge-Vorschlägen und Retrieval-Ergebnissen führt.

Wichtigste Punkte:

1. Jedes Profil benötigt key, label, note_type und steps
2. WP-26 Features (section_type, block_id, generate_block_id, references) sind nur für capture_text und capture_text_line verfügbar
3. Block-IDs müssen eindeutig sein (automatische Nummerierung in Loops)
4. Referenzen müssen auf vorherige Sections verweisen
5. Ein Review-Step sollte immer am Ende stehen

---

Ende der Interview Config Guide