mindnet_obsidian/docs/09_Workbench_Analysis_Basis.md

Chain Workbench - Analyse-Basis und Erweiterungen

Version: 0.5.x
Stand: 2025-01-XX
Zielgruppe: Entwickler, Architekten

---

Übersicht

Die Chain Workbench (0.5.x) basiert hauptsächlich auf den Analysen aus Chain Inspector (0.4.x), erweitert diese aber um zusätzliche Heuristiken und granularere Todo-Generierung.

---

Basis: Chain Inspector 0.4.x Analysen

Template Matching (0.4.x)

Die Workbench nutzt direkt die Template Matches aus Chain Inspector:

• TemplateMatch Interface:
  • templateName: Name des Templates
  • score: Match-Score (+10 pro Link, +2 pro Slot, -5 pro fehlendem required Link)
  • slotAssignments: Map von Slot-ID → Node-Referenz
  • missingSlots: Array von fehlenden Slot-IDs
  • satisfiedLinks: Anzahl erfüllter Links
  • requiredLinks: Anzahl erforderlicher Links
  • roleEvidence: Array von Edge-Role-Evidence
  • slotsComplete: Boolean
  • linksComplete: Boolean
  • confidence: "confirmed" | "plausible" | "weak"

Quelle: src/analysis/chainInspector.ts → inspectChains() → matchTemplates()

Findings aus 0.4.x (aktuell NICHT verwendet, aber sollten integriert werden)

Status: Die Findings aus Chain Inspector werden aktuell nicht in der Workbench verwendet, obwohl sie aufwendig getestet wurden und wertvolle Informationen liefern.

Findings aus 0.4.x:

• missing_edges - Section hat Content aber keine Edges
• one_sided_connectivity - Nur incoming oder nur outgoing edges
• only_candidates - Nur Candidate-Edges, keine expliziten
• dangling_target - Target-Datei existiert nicht
• dangling_target_heading - Target-Heading existiert nicht
• no_causal_roles - Section hat Edges aber keine kausalen Rollen
• missing_slot_<slotId> - Template-basiert: Slot fehlt (aggregiert)
• missing_link_constraints - Template-basiert: Links fehlen (aggregiert)
• weak_chain_roles - Template-basiert: Nur non-causal Rollen (aggregiert)

Warum aktuell nicht verwendet?

• Die Workbench fokussiert sich aktuell nur auf Template-basierte Todos
• Findings sind teilweise aggregiert (z.B. "missing_slot_trigger" für alle Matches)
• Workbench benötigt granulare Todos pro Match (z.B. "missing_slot_trigger" für jeden Match einzeln)
• Workbench benötigt konkrete Actions (z.B. insert_edge_forward, create_note_via_interview)

Sollten integriert werden: Die Findings könnten als zusätzliche Todos integriert werden:

• dangling_target → Todo mit Action create_missing_note oder retarget_link
• dangling_target_heading → Todo mit Action create_missing_heading oder retarget_to_existing_heading
• only_candidates → Todo mit Action promote_all_candidates oder create_explicit_edges
• missing_edges → Todo mit Action add_edges_to_section
• no_causal_roles → Todo ähnlich wie weak_roles, aber section-weit (nicht template-basiert)
• one_sided_connectivity → Informatives Todo (keine Action, nur Hinweis)

Vorteil der Integration:

• Nutzung der getesteten Heuristiken aus 0.4.x
• Vollständigere Analyse (nicht nur Template-basiert)
• Konsistenz zwischen Chain Inspector und Workbench

---

Neue Analysen in 0.5.x

1. Status-Berechnung (statusCalculator.ts)

Neu in 0.5.x: Berechnet MatchStatus basierend auf Slot/Link-Erfüllung:

• complete: slotsFilled == slotsTotal && linksSatisfied == linksRequired
• near_complete:
  • slotsFilled == slotsTotal && (linksRequired - linksSatisfied) in {1,2}
  • ODER (slotsTotal - slotsFilled) == 1 && linksSatisfied == linksRequired
• weak: Match vorhanden, aber nur structural/temporal Rollen (keine causal)
• partial: Sonstige Fälle mit mindestens einer Lücke

Basis: TemplateMatch aus 0.4.x, aber neue Heuristik für Status-Kategorisierung.

2. Granulare Todo-Generierung (todoGenerator.ts)

Neu in 0.5.x: Generiert konkrete Todos pro Match:

missing_slot Todo

• Basis: match.missingSlots aus TemplateMatch
• Erweiterung:
  • Pro Slot ein Todo (nicht aggregiert)
  • Enthält allowedNodeTypes für Interview-Filterung
  • Enthält Actions: ["link_existing", "create_note_via_interview"]

missing_link Todo

• Basis: Template-Links aus template.links + match.slotAssignments
• Erweiterung:
  • Prüft, ob beide Slots gefüllt sind, aber Link fehlt
  • Enthält fromNodeRef und toNodeRef (konkrete Referenzen)
  • Enthält suggestedEdgeTypes aus chain_roles.yaml
  • Enthält Actions: ["insert_edge_forward", "insert_edge_inverse", "choose_target_anchor"]

weak_roles Todo

• Basis: match.roleEvidence aus TemplateMatch
• Erweiterung:
  • Prüft, ob alle Rollen structural/temporal sind (keine causal)
  • Enthält Liste von edges mit currentRole und suggestedRoles
  • Enthält Actions: ["change_edge_type"]

candidate_cleanup Todo (NEU)

• Basis: Candidate-Edges aus graphIndex + missing_link Todos
• Vollständig neu:
  • Findet Candidate-Edges, die zu missing_link Requirements passen
  • Relation-Equality-Check: Prüft, ob bereits ein confirmed Edge für dieselbe Relation existiert
  • Wenn ja → kein Todo (verhindert Duplikate)
  • Wenn nein → Todo mit promote_candidate Action

Relation-Equality-Logik:

// Prüft:
// 1. Direction match (from → to)
// 2. Node-Refs match (file + heading)
// 3. Canonical Edge-Type match (via edge_vocabulary.md)

3. Effective Required Links Resolution

Neu in 0.5.x: Resolved required_links Flag mit Priorität:

1. template.matching?.required_links (höchste Priorität)
2. profile.required_links
3. defaults.matching?.required_links
4. Fallback: false

Basis: TemplateMatch nutzt bereits requiredLinks, aber Workbench benötigt explizite Resolution für UI-Darstellung.

---

Vergleich: Findings vs. Todos

Aspekt	Chain Inspector 0.4.x (Findings)	Chain Workbench 0.5.x (Todos)
Granularität	Aggregiert (pro Template-Typ)	Granular (pro Match, pro Slot/Link)
Format	Finding Interface (code, severity, message)	WorkbenchTodoUnion Interface (type, actions, refs)
Actions	Keine (nur Informativ)	Konkrete Actions (insert_edge_forward, etc.)
Basis	Template Matches + Gap-Heuristiken	Template Matches + zusätzliche Analysen
Verwendung	Console-Output, Fix Findings Command	Workbench UI, interaktive Bearbeitung

---

Abhängigkeiten

Direkte Abhängigkeiten (0.4.x)

1. TemplateMatch aus chainInspector.ts

   • Wird direkt verwendet für Status-Berechnung und Todo-Generierung

2. ChainTemplatesConfig aus dictionary/types.ts

   • Wird verwendet für Slot/Link-Definitionen und allowed_node_types

3. ChainRolesConfig aus dictionary/types.ts

   • Wird verwendet für suggestedEdgeTypes in missing_link Todos

4. EdgeVocabulary aus vocab/types.ts

   • Wird verwendet für Canonical-Type-Resolution (Relation-Equality)

5. IndexedEdge[] aus graphIndex.ts

   • Wird verwendet für Candidate/Confirmed-Edge-Trennung

Indirekte Abhängigkeiten

1. Template Matching Algorithmus (0.4.x)

   • Backtracking-Algorithmus für Slot-Assignment
   • Scoring-Mechanismus (+10 pro Link, +2 pro Slot, -5 pro fehlendem required Link)

2. Edge-Role-Mapping (0.4.x)

   • chain_roles.yaml → Edge-Types → Roles
   • Wird verwendet für weak_roles Detection

---

Neue Heuristiken (nicht in 0.4.x)

1. Relation-Equality-Check

Zweck: Verhindert Duplikate bei Candidate-Cleanup.

Logik:

• Prüft, ob bereits ein confirmed Edge für dieselbe Relation existiert
• Relation = (fromNodeRef, toNodeRef, canonicalEdgeType)
• Wenn ja → kein candidate_cleanup Todo

Implementierung: todoGenerator.ts → checkRelationExists()

2. Status-Kategorisierung

Zweck: Priorisierung von Matches in Workbench UI.

Logik:

• complete → höchste Priorität (grün)
• near_complete → hohe Priorität (gelb)
• partial → mittlere Priorität (orange)
• weak → niedrige Priorität (rot)

Implementierung: statusCalculator.ts → calculateMatchStatus()

3. Effective Required Links Resolution

Zweck: Korrekte Darstellung von Link-Requirements in UI.

Logik:

• Resolved required_links Flag mit Priorität (template > profile > defaults)
• Beeinflusst, ob missing_link Todos generiert werden

Implementierung: statusCalculator.ts → getEffectiveRequiredLinks()

---

Zusammenfassung

Basierend auf 0.4.x

✅ Template Matches - Direkt verwendet
✅ Slot-Assignments - Direkt verwendet
✅ Missing Slots - Direkt verwendet
✅ Role Evidence - Direkt verwendet
✅ Edge-Role-Mapping - Direkt verwendet
✅ Canonical Edge Types - Direkt verwendet

Neu in 0.5.x

🆕 Status-Berechnung - Neue Heuristik
🆕 Granulare Todos - Pro Match, pro Slot/Link
🆕 Candidate-Cleanup - Relation-Equality-Check
🆕 Effective Required Links - Prioritäts-Resolution
🆕 Action-System - Konkrete Actions pro Todo

Nicht verwendet aus 0.4.x (sollten integriert werden)

⚠️ Findings - Werden aktuell nicht verwendet, sollten aber integriert werden
⚠️ Gap-Heuristiken - Werden aktuell nicht verwendet, sollten aber integriert werden
⚠️ Dangling Target Checks - Werden aktuell nicht verwendet, sollten aber integriert werden

Empfehlung: Die Findings sollten als zusätzliche Todos in die Workbench integriert werden, um die getesteten Heuristiken zu nutzen und eine vollständigere Analyse zu bieten.

---

Fazit

Die Chain Workbench (0.5.x) basiert hauptsächlich auf den Template Matches aus Chain Inspector (0.4.x), erweitert diese aber um:

1. Granulare Todo-Generierung (pro Match, pro Slot/Link)
2. Status-Kategorisierung (complete, near_complete, partial, weak)
3. Candidate-Cleanup-Heuristik (Relation-Equality-Check)
4. Action-System (konkrete Actions pro Todo)

Aktueller Stand: Die Workbench verwendet aktuell nur die Template Matches aus 0.4.x, nicht die Findings. Dies ermöglicht eine interaktive Bearbeitung mit konkreten Actions.

Empfohlene Erweiterung: Die Findings aus 0.4.x sollten als zusätzliche Todos integriert werden, um:

• Die getesteten Heuristiken zu nutzen
• Eine vollständigere Analyse zu bieten (nicht nur Template-basiert)
• Konsistenz zwischen Chain Inspector und Workbench zu gewährleisten

Nächste Schritte:

1. Findings aus report.findings in buildWorkbenchModel einlesen
2. Findings zu Todos konvertieren (mit entsprechenden Actions)
3. Findings-Todos zu den Template-basierten Todos hinzufügen
4. UI erweitern, um beide Todo-Typen anzuzeigen

---

Letzte Aktualisierung: 2025-01-XX
Version: 0.5.x