mindnet/docs/02_concepts/02_causal_chain_retrieving.md

Mindnet Causal Assistant – Dokumentation der bisher erreichten Resultate (0.4.x) + Architektur, Konfiguration & Strategien

Stand: basierend auf den beobachteten Chain-Inspector-Logs und den zuletzt beschriebenen Implementierungen in 0.4.6/0.4.x.
Ziel dieser Doku: Eine einheitliche, belastbare Basis, damit Weiterentwicklung (0.5.x/0.6.x) nicht mehr “im Kreis” läuft.

---

1) Zweck & Gesamtziel von Mindnet

Mindnet soll in einem Obsidian Vault kausale/argumentative Zusammenhänge als Graph abbilden und daraus nützliche Diagnosen ableiten:

• Graph-Aufbau: Notes/Sections als Knoten, Links/Kanten als gerichtete Beziehungen (z.B. wirkt_auf, resulted_in, depends_on …).
• Analyse aus einem Kontext: Nutzer steht in einer Note an einer bestimmten Überschrift/Section → Mindnet analysiert lokale Nachbarschaft + Pfade im Graphen.
• Template Matching: Einordnen der gefundenen Knoten/Kanten in “Kettenmuster” (Chain Templates) wie z.B. trigger → transformation → outcome oder loop_learning.
• Findings (Gap-Heuristiken): Hinweise wie “fehlende Slots”, “fehlende Links”, “unmapped edge types”, “einseitige Konnektivität”, etc.
  → Ziel: Nutzer konkret zum besseren Graphen führen, ohne “Noisy” zu sein.

---

2) Begriffe & Datenmodell (so arbeitet der Chain Inspector)

2.1 Kontext (Context)

Der Chain Inspector läuft immer gegen einen aktuellen Kontext:

• file: aktuelle Note (z.B. Tests/03_insight_transformation.md)
• heading: aktuelle Section (z.B. Kern)
• zoneKind: i.d.R. content

Das ist wichtig, weil Kanten teils section-spezifisch sind und teils (geplant/teilweise offen) note-weit gelten könnten.

---

2.2 Knoten (Nodes)

Ein Knoten ist im Report meist referenziert als:

• file + heading (z.B. Tests/01_experience_trigger.md:Kontext)
• plus abgeleitete Metadaten wie noteType (z.B. experience, insight, decision, event)

noteType ist entscheidend fürs Template Matching (Slots).

---

2.3 Kanten (Edges)

Eine Kante hat typischerweise:

• rawEdgeType: Original-Typ aus Markdown/Notation (z.B. wirkt_auf, resulted_in, depends_on, derived_from, …)
• from: Quelle (file:heading)
• to: Ziel (file:heading)
• scope: Gültigkeit / Herkunft
  • section: Edge ist “voll gültig” für die Section
  • candidate: Edge ist nur Kandidat/unsicher, wird optional zugelassen
  • (geplant/offen) note: Edge gilt note-weit (unabhängig von Section)
• evidence: Fundstelle (file, sectionHeading, lineRange)

---

3) Erreichte Resultate in 0.4.x (verifiziert)

3.1 includeCandidates – Kandidatenkanten funktionieren wie erwartet

Ergebnis (bereits mehrfach in Logs verifiziert):

• Wenn includeCandidates=false, werden Kanten mit scope: candidate im effektiven Graphen ausgefiltert.
• Wenn includeCandidates=true, werden Kandidatenkanten als incoming/outgoing berücksichtigt und tauchen in neighbors/paths auf.

Implikation:

• Das System kann “unsichere” oder “LLM-vorschlagene” Verbindungen existieren lassen, ohne in jedem Lauf die Analyse zu verfälschen.
• In “Discovery” kann man Kandidaten zulassen (mehr Explorationspower).
• In “Decisioning” kann man Kandidaten typischerweise sperren (mehr Verlässlichkeit).

---

3.2 required_links: Strict vs Soft Mode – missing_link_constraints Unterdrückung ist umgesetzt

Problem (historisch):

• missing_link_constraints wurde teilweise auch dann ausgegeben, wenn required_links=false (Soft Mode) aktiv war → unnötig “noisy”.

Fix (laut Cursor-Report umgesetzt + Tests):

• missing_link_constraints wird nur erzeugt, wenn effectiveRequiredLinks === true.
• Es gibt eine definierte Auflösungsreihenfolge für required_links:

Resolution Order (effective required_links):

1. template.matching?.required_links
2. profile.required_links
3. defaults.matching?.required_links
4. Fallback: false

Transparenz bleibt erhalten:

• satisfiedLinks und requiredLinks werden weiterhin im Report angezeigt.
• linksComplete bleibt als technischer Wert im Report bestehen.
• Nur das Finding missing_link_constraints wird unterdrückt, nicht die Fakten.

Implikation:

• Soft Mode (= required_links=false) ist jetzt ruhig genug, um “Entdeckung” zu unterstützen.
• Strict Mode (= required_links=true) eignet sich für harte Qualitätskontrolle.

---

3.3 “Healthy graph” → Findings leer ([]), Template “confirmed”

Wenn Slots und geforderte Links erfüllt sind (z.B. trigger_transformation_outcome mit 2/2 Links), dann ist findings: [] das erwartete Ergebnis.

Implikation:

• Das ist das zentrale “Green Path”-Signal: Graph ist konsistent für das gewählte Template/Profil.

---

3.4 Unmapped edges werden erkannt (Diagnose)

Wenn ein rawEdgeType nicht in die kanonischen Rollen/Edge-Rollen abgebildet werden kann, tauchen typischerweise Diagnosen auf:

• edgesUnmapped > 0
• Findings wie no_causal_roles oder link constraints bleiben unerfüllt

Implikation:

• Das Rollen-Mapping (chain_roles.yaml) ist “critical path”: wenn ein Edge-Typ nicht gemappt wird, bricht oft der kausale Interpretationspfad.

---

4) Was ist (noch) offen – echtes nächstes Verifikationsziel

4.1 Note-Level Edges / Note-Scope (“für jede Sektion gültig”)

Es existiert ein Konzept/Einbau: In 02_event_trigger_detail gibt es einen Bereich, der Kanten auf Note-Ebene definieren soll (unabhängig von aktueller Section).

Offen ist die robuste Verifikation (oder Implementierung), dass:

• diese Edges auch dann gelten, wenn der Cursor in einer anderen Section derselben Note steht,
• idealerweise mit klar erkennbarer Kennzeichnung wie scope: note im Report.

Warum ist das wichtig?

• Das ermöglicht “globaler Kontext” pro Note, ohne alles in jede Section duplizieren zu müssen.
• Es ist eine UX-Optimierung: Nutzer kann “Meta-Verbindungen” an einer Stelle pflegen.

---

5) Konfigurationsdateien – Rolle & Interpretation (Mindnet-Strategie)

Die folgenden Bereiche beschreiben eine saubere, konsistente Interpretation, wie Mindnet die Configs verwenden sollte.
Konkrete Keys, die in Logs sichtbar waren (z.B. required_links, min_slots_filled_for_gap_findings, min_score_for_gap_findings) sind hier berücksichtigt.

5.1 chain_templates.yaml – “Welche Ketten gibt es, wie werden sie gematcht?”

Zweck:

• Definiert Templates (Muster), z.B.:
  • trigger_transformation_outcome
  • loop_learning
  • ggf. weitere (constraint_to_adaptation usw.)

Template enthält typischerweise:

• Slots (Rollen für Knoten): z.B. trigger, transformation, outcome, experience, learning, behavior, feedback
• Required Link Constraints (welche Slot-zu-Slot Verbindungen zwingend sind)
• Scoring/Matching-Parameter (ggf. weights, thresholds)
• Optional: template-level override für required_links

Matching-Profile (wie in Logs sichtbar):

• z.B. Profile: discovery, decisioning
• Parameter im Profil (sichtbar in Logs):
  • required_links (strict vs soft)
  • min_slots_filled_for_gap_findings
  • min_score_for_gap_findings
  • ggf. maxTemplateMatches

Interpretation:

• Templates liefern die “Soll-Struktur”
• Profile bestimmen “Wie streng” wir die Soll-Struktur im jeweiligen Workflow bewerten

---

5.2 chain_roles.yaml – “Welche rawEdgeTypes zählen als welche Rollen?”

Zweck:

• Mappt rawEdgeType → kanonische Rollen/EdgeRoles (z.B. causal, influences, enables_constraints, provenance).
• Diese Rollen sind Grundlage für:
  • no_causal_roles Finding
  • Link-Constraint-Satisfaction (Template erwartet “causal” zwischen Slots)
  • Matching Score (welche Edges zählen für welches Template)

Interpretation:

• Wenn ein Edge-Typ nicht gemappt ist:
  • Edge kann trotzdem im Graph auftauchen,
  • aber Template/Constraint-Logik kann ihn nicht “verstehen” → führt zu Findings.

---

5.3 analysis_policies.yaml – “Wie noisy dürfen Findings sein?”

Zweck:

• Zentrale Policies für Findings:
  • welche Finding-Codes existieren
  • Default-Severity (info/warn/error)
  • Profilabhängige Overrides
  • Unterdrückungsregeln (z.B. suppress in soft mode, suppress wenn confirmed, suppress wenn Score hoch…)

Interpretation:

• Policies sind “produktseitige UX-Regeln”:
  • Discovery: eher informativ, weniger warn
  • Decisioning: klare Warnungen, wenn Qualität fehlt
• Der bereits umgesetzte Fix (missing_link_constraints nur in strict) ist exakt so eine Policy-Entscheidung (auch wenn technisch im Inspector gelöst).

---

6) Ablauf des Chain Inspectors (Vorgehensweise in Mindnet)

Hier ist ein konsistenter “Pipeline”-Ablauf, der zu den Logs passt:

Schritt 1: Kontext bestimmen

• Aktuelle Datei + aktuelle Section/Heading

Schritt 2: Edges aus aktueller Note laden

• Outgoing aus der aktuellen Section extrahieren (oder aus einem definierten Block)
• (optional/offen) Note-Level Edges ebenfalls laden und für jede Section gültig machen

Schritt 3: Nachbarn laden

• Backlinks (Notes, die auf die aktuelle Note verlinken) → incoming Kandidatenquellen
• Outgoing Neighbor Notes (Notes, auf die aktuelle Note verweist) → Nachbarschaft erweitern

Schritt 4: Edges aus Neighbor Notes laden

• Aus den verlinkenden Notes die Edges extrahieren, die auf die aktuelle Note/Section zielen
• Canonicalization: rawEdgeTypes via chain_roles.yaml in Rollen überführen

Schritt 5: Kandidatenfilter / Scopefilter anwenden

• Wenn includeCandidates=false:
  • scope: candidate aus effective graph entfernen
• Optional weitere Filter:
  • includeNoteLinks / includeSectionLinks
  • direction (forward/backward/both)
  • maxDepth (Traversal)

Schritt 6: Pfade berechnen (Paths)

• Forward/Backward (oder both)
• BFS/DFS bis maxDepth
• Resultat: Pfadlisten mit nodes + edges

Schritt 7: Template Matching

• Kandidatenknoten für Slots finden (via noteType + Nähe + Pfade)
• Links/Constraints prüfen (erwartete slot→slot Beziehungen)
• Score berechnen (z.B. per:
  • Slots erfüllt
  • Link constraints erfüllt
  • “RoleEvidence” passend)

Schritt 8: Findings berechnen (Gap-Heuristics)

Beispiele:

• missing_slot_* wenn wichtige Slots fehlen (abhängig von Profil-Thresholds)
• one_sided_connectivity wenn nur incoming oder nur outgoing
• no_causal_roles wenn Edges da, aber keine causal Rollen im effektiven Graph
• missing_link_constraints nur wenn effectiveRequiredLinks=true und slotsComplete=true, requiredLinks>0, linksComplete=false

Schritt 9: Report ausgeben

• context, settings, neighbors, paths, findings, analysisMeta, templateMatches
• Transparenz: satisfiedLinks/requiredLinks/linksComplete bleiben sichtbar

---

7) Strategien, die Mindnet verfolgen kann (Produkt-/UX-Strategie)

Strategie A: Discovery (Exploration)

Ziel: Möglichst schnell “wo könnte eine sinnvolle Kette entstehen?” finden.

• required_links = false (Soft Mode)
• includeCandidates = true (optional)
• findings eher informativ (info), weniger warn
• Templates mehr als Vorschläge (“plausible/weak”), nicht als harte Bewertung

Vorteil: Nutzer bekommt schnell Hypothesen.
Risiko: Mehr Noise, mehr falsche Kandidaten – muss per Policy gedämpft werden.

---

Strategie B: Decisioning (Qualitätskontrolle)

Ziel: Prüfung, ob eine Kette “wirklich steht” und als belastbar gelten kann.

• required_links = true (Strict Mode)
• includeCandidates = false
• findings: warn, wenn Slots/Links fehlen
• “confirmed” nur wenn link constraints komplett

Vorteil: Qualitätssicherung & Verlässlichkeit.
Risiko: Nutzer fühlt sich “blockiert”, wenn Graph noch im Aufbau ist.

---

Strategie C: Progressive Disclosure (hybrid)

Ziel: Nutzer nicht überfordern, aber zielgerichtet verbessern.

• Soft Mode für Einstieg
• Button/Toggle: “Strict prüfen”
• Candidate Edges als Vorschlag-Klasse (UI: “proposed edges”)
• Findings priorisieren: erst fehlende Slots, dann fehlende Links, dann Detail-Qualität

---

8) Wie ein “kausaler Retriever” funktionieren könnte (Causal Retriever)

Ein kausaler Retriever ist die Komponente, die aus dem Vault/Graphen relevante Kausalkontexte für den aktuellen Abschnitt liefert – idealerweise deterministisch, skalierbar und template-aware.

8.1 Retrieval-Ziele

• Finde Knoten/Edges, die kausal relevant sind zum aktuellen Kontext:
  • Ursachen (backward)
  • Wirkungen/Entscheidungen (forward)
  • Bedingungen/Constraints (seitlich)
• Gib nicht nur Knoten zurück, sondern:
  • Pfade (explainable)
  • Evidence (wo steht das)
  • Role-Interpretation (warum ist das causal/influences/etc.)

8.2 Retrieval-Inputs

• startNode = current section
• direction = forward/backward/both
• maxDepth
• roleFilter (optional): nur causal/influences/enables_constraints
• scopeFilter: includeCandidates, includeNoteLevel
• templateBias: bevorzugte Pfadformen (z.B. “experience→insight→decision”)

8.3 Retrieval-Algorithmus (praktisch)

Variante 1: BFS mit Rolle-Gewichtung

• BFS über Kanten
• Priorität/Score pro Frontier:
  • causal > influences > provenance
  • section-scope > note-scope > candidate (wenn candidates eingeschaltet, sonst candidate=∞)
• Stop, wenn:
  • maxDepth erreicht
  • genug Top-N Pfade gesammelt (z.B. topNUsed)

Variante 2: Template-driven Retrieval

• Wenn ein Template im Fokus ist:
  • suche explizit nach Slot-Knoten (noteType matching)
  • suche dann die minimalen Verbindungen, die Constraints erfüllen
• Gute Option für “Decisioning”: deterministisch prüfen.

Variante 3: Two-phase Retrieval

1. Kandidaten finden (Slots)
2. Verbindungen prüfen (Constraints) → Liefert sehr gut “warum fehlt Link X?” Diagnosen.

8.4 Output-Format

• neighbors (incoming/outgoing, mit evidence)
• paths (forward/backward, nodes+edges)
• plus “slot candidates” optional (für UI)

---

9) Empfehlungen für robuste Tests (damit ihr nicht wieder im Kreis lauft)

Was ist bereits ausreichend getestet (nicht wiederholen)

• includeCandidates Filterverhalten ✅
• missing_link_constraints Unterdrückung bei required_links=false ✅
• strict/soft required_links via profile/template override ✅
• “healthy graph” ergibt findings: [] ✅
• unmapped edge type triggert Diagnose ✅

Was als einziges “neues” Testziel für Abschluss 0.4.x/Start 0.5.x taugt

• Note-level edges / note-scope: gelten Kanten “global” pro Note oder nicht?

Minimal-Testdefinition (einmalig, reproduzierbar):

1. In 02_event_trigger_detail.md einen klaren Note-Level Block definieren (z.B. “## Note-Verbindungen”).
2. Edge dort definieren, die auf eine andere Note/Section zeigt.
3. Cursor in einer anderen Section derselben Note platzieren (z.B. “## Detail” oder “## Extra”).
4. Chain Inspector laufen lassen.
5. Erwartung:
   • Edge erscheint trotzdem als outgoing/incoming
   • evidence zeigt auf den Note-Level Block
   • ideal: scope: note

Wenn das FAIL ist → klarer 0.5.0 Task.

---

10) Implikationen für 0.5.x / 0.6.x (wohin sinnvoll weiter)

0.5.x (Stabilisierung)

• Note-level edge scope finalisieren (inkl. Report-Transparenz)
• policies (analysis_policies) als zentrale Noise-Steuerung weiter ausbauen
• Debug/Explainability weiter verbessern (effectiveRequiredLinks pro Match explizit ausgeben)

0.6.x (UX & Workflows)

• Actionable Findings: “Was genau soll ich ändern?” inkl. Vorschlagtext oder Snippet
• UI-Toggles: Strict/Soft, Candidates on/off
• Template Authoring Tools: Linter, “Warum kein Match?”

---

11) Kurzes “Was heißt das für Mindnet im Alltag?”

• Im Discovery-Modus: Mindnet ist ein Explorationswerkzeug (Hypothesen + Hinweise, wenig Warnungen).
• Im Decisioning-Modus: Mindnet ist ein Qualitätsprüfer (strict, wenige false positives).
• Der nächste große Hebel ist Note-scope: Damit wird Pflege einfacher und Ketten werden “wartbarer”.

---

12) Appendix: Beispielhafte Report-Signale (Interpretationshilfe)

• findings: [] + confidence: confirmed
  → Template passt sauber (Slots + Links vollständig im gewählten Modus).

• linksComplete=false aber required_links=false und kein missing_link_constraints
  → Soft Mode: bewusst kein “Warn-Noise”, aber Transparenz bleibt.

• no_causal_roles
  → Edges existieren, aber keine davon wird als “causal” interpretiert (Mapping oder rawEdgeType Problem).

• edgesUnmapped > 0
  → chain_roles unvollständig oder Edge-Typ ist neu/fehlerhaft geschrieben.

• effectiveIncoming=0 bei includeCandidates=false, aber incoming candidate-edge existiert
  → Filter funktioniert wie geplant.

---

ENDE