mindnet_obsidian/docs/09_Chain_Inspector_Workbench_Lastenheft.md

LASTENHEFT: Chain Inspector & Chain Workbench

Version: 1.0
Datum: 28. Januar 2026
Status: Entwurf
Projekt: mindnet_obsidian (Obsidian Community Plugin)
Bezug: WP-26 Integration (06_LH_WP26_Plugin_Integration.md), FA-PL-08; Chain Inspector v0.4.x / v0.4.2; Chain Workbench Findings Integration (10_Workbench_Findings_Integration.md)

---

1. Einleitung

1.1 Zweck

Dieses Lastenheft definiert die vollständigen fachlichen und technischen Anforderungen für die Kausal-Funktionen Chain Inspector und Chain Workbench im mindnet_obsidian Plugin. Es umfasst:

• Die Integration der Section-Type-Logik (effective_type) in Chain-Analyse und Workbench (FA-PL-08).
• Die Anforderungen aus den früheren Implementierungsberichten (Chain Inspector v0.0–v0.4.2, Chain Workbench 0.5.x).
• Offene Punkte aus dem Vorschlag Workbench Findings Integration (Findings → Todos, Actions).
• Commands, Sichtbarkeit, Dictionary-Abhängigkeiten und UX.

1.2 Geltungsbereich

• Chain Inspector: Analyse kausaler Ketten um die aktuelle Section (Template-Matching, Findings, Rollen, Gaps).
• Chain Workbench: UI für Findings, Template-Matches, TODOs und Fix-Actions.
• Section-Types: Explizite Typen pro Abschnitt ([!section] type), Fallback auf Note-Type; Verwendung als effective_type in Chain-Matching.

1.3 Abhängigkeiten

• Backend: WP-26 (Section Types & Intra-Note-Edges).
• Plugin: Section-Type-Callout-Parsing (FA-PL-01), Block-ID-Extraktion (FA-PL-02), Types-Loader (FA-PL-13).
• Dictionary: chain_roles.yaml, chain_templates.yaml, edge_vocabulary.md, optional types.yaml, graph_schema.md.

---

2. Begriffe und Definitionen

Begriff	Definition
Effective Type	Für einen Knoten (Section/Note): sectionType || noteType. Wird für Template-Slot-Matching und Gap-Detection verwendet.
Section-Type	Explizit per > [!section] type definierter Typ eines Abschnitts.
Note-Type	Aus Frontmatter type: der Note.
Template Match	Zuweisung von Candidate-Nodes zu Template-Slots unter Berücksichtigung von allowed_node_types und allowed_edge_roles.
Finding	Ein vom Chain Inspector erzeugtes Analyseergebnis (z. B. no_causal_roles, missing_link, dangling_target).
Workbench Todo	Aus Finding oder Template-Match abgeleitete konkrete Aufgabe mit Priorität und optionalen Actions.

---

3. Chain Inspector – Anforderungen

3.1 Kernfunktion

• Eingabe: Aktuelle Datei + aktuelle Section (Cursor-Position / Heading).
• Ausgabe: ChainInspectorReport mit Nachbarn, Pfaden, Findings, Template-Matches, Analyse-Meta, Templates-Source, optional Template-Matching-Profile.

3.2 Effective Type (Section-Type-Integration)

LH-CI-01: Effective Type pro Knoten

• Für jeden Knoten (file + heading) muss ein effective_type ermittelt werden.
• Regel: effectiveType = sectionType || noteType.
• sectionType: Aus geparster Note: Section, die durch heading identifiziert wird, enthält ein [!section] type Callout → dieser Typ.
• noteType: Aus Frontmatter type: der zugehörigen Datei.
• Fallback: Wenn weder Section-Type noch Note-Type vorhanden: "unknown".

Betroffene Stellen:

• src/analysis/templateMatching.ts: Aktuell wird nur extractNoteType(content) pro Datei verwendet; für Section-Knoten (mit heading) muss pro Section der Section-Type aus dem geparsten Dokument gelesen werden.
• src/analysis/chainInspector.ts: Report und Findings müssen effective_type unterstützen (z. B. in SlotAssignments oder Meta).
• src/mapping/sectionParser.ts: Muss [!section] erkennen und sectionType in NoteSection liefern (vgl. FA-PL-01); aktuell fehlt sectionType in NoteSection.

3.3 Template-Matching mit Section-Types

LH-CI-02: Slot-Matching mit effective_type

• Beim Zuordnen von Candidate-Nodes zu Template-Slots gilt: Slot-Constraint allowed_node_types wird gegen effective_type des Knotens geprüft (nicht nur gegen noteType).
• Bestehende Logik in nodeMatchesSlot(node, slot) muss mit node.effectiveType (oder äquivalent) arbeiten.

LH-CI-03: Provenance

• Im Report soll erkennbar sein, ob ein Slot-Type aus Section-Type oder Note-Type stammt (optional: typeSource: "section" | "note" | "unknown" pro Slot-Zuordnung).

3.4 Findings

LH-CI-04: Bestehende Finding-Codes

• Folgende Finding-Codes müssen unterstützt und dokumentiert sein:
  • dangling_target, dangling_target_heading
  • only_candidates, missing_edges, no_causal_roles, one_sided_connectivity
  • missing_slot_<slotId>, weak_chain_roles
  • Optional: slot_type_mismatch (v0.4 Report: bisher nicht implementiert, da Matching Mismatches verhindert).

LH-CI-05: Findings mit Section-Type-Kontext

• Findings können optional effectiveType der betroffenen Section bzw. des Knotens enthalten (für bessere Workbench-Todos und Fix-Actions).

3.5 Gap-Detection und Section-Types

LH-CI-06: Fehlende Section-Types als Gap

• Wenn ein Template einen Slot mit z. B. allowed_node_types: ["experience"] vorsieht und die aktuelle Section keinen Section-Type hat, aber der Note-Type z. B. "concept" ist, soll dies als Gap/Finding behandelbar sein (z. B. „Section-Type setzen oder Note-Type anpassen“).
• Konkret: Gap-Detection soll erkennen, wenn effective_type nicht zu den erlaubten Slot-Types passt, und ggf. ein Finding/Todo vorschlagen (z. B. „Add Section Type experience“).

3.6 Dictionary-Abhängigkeiten

LH-CI-07: Verhalten bei fehlenden Dictionaries

• Wenn chain_roles.yaml oder chain_templates.yaml nicht geladen werden können:
  • Es soll eine Notice angezeigt werden (z. B. „Chain Roles nicht geladen. Bitte Pfad in den Einstellungen prüfen.“) und der Command abbrechen (kein stilles Weiterlaufen mit reduzierter Funktionalität).
• Implementierungsstand: In main.ts wurde bereits eine Prüfung und Notice eingebaut; im Lastenheft wird dies als verbindlich festgehalten.

3.7 Commands und Sichtbarkeit

LH-CI-08: Command „Mindnet: Inspect Chains (Current Section)“

• ID: mindnet-inspect-chains.
• Kontext: editorCallback (nur bei geöffneter Markdown-Datei).
• Verhalten: Führt Chain Inspector aus, gibt Report in Console aus (oder vergleichbar).
• Optional (FA-PL-12a): Zusätzlicher Command ohne editorCallback, der bei fehlender Datei eine Notice anzeigt, damit der Befehl in der Palette sichtbar bleibt.

---

4. Chain Workbench – Anforderungen

4.1 Kernfunktion

• Eingabe: Wie Chain Inspector (aktuelle Datei + Section) plus geladene Chain-Templates, Chain-Roles, Edge-Vocabulary.
• Ausgabe: Workbench-Model mit Matches (Template-Matches inkl. Status/Todos) und globalTodos (aus Findings).

4.2 Section-Type in Workbench-Model

LH-CW-01: WorkbenchMatch mit Section-Types

• Jeder Match soll optional effective_type (oder Section-Type) pro zugewiesenem Slot führen (für Anzeige und für Todo-Vorschläge).
• Vgl. WP26-Spezifikation: sectionTypes?: Map<string, string>.

LH-CW-02: Todos mit Section-Type-Kontext

• Missing-Link- und Missing-Slot-Todos sollen fromSectionType / toSectionType (bzw. effective_type) enthalten, damit Edge-Type-Vorschläge aus graph_schema.md korrekt berechnet werden können.

4.3 Findings → Todos (Workbench Findings Integration)

LH-CW-03: Generierung von Todos aus Findings

• Die in 10_Workbench_Findings_Integration.md beschriebene Funktion generateFindingsTodos() soll umgesetzt werden:
  • Eingabe: Finding[], IndexedEdge[], Kontext { file, heading }.
  • Ausgabe: WorkbenchTodoUnion[] (u. a. DanglingTargetTodo, OnlyCandidatesTodo, NoCausalRolesTodo, MissingEdgesTodo, OneSidedConnectivityTodo).
• Todo-Typen sind in src/workbench/types.ts bereits definiert (dangling_target, only_candidates, no_causal_roles, etc.); die Generierung aus Findings und die Integration in buildWorkbenchModel() sind umzusetzen.

LH-CW-04: Integration in buildWorkbenchModel

• buildWorkbenchModel() soll neben Template-Match-basierten Todos auch globalTodos aus report.findings erzeugen (über generateFindingsTodos()).
• WorkbenchModel soll globalTodos?: WorkbenchTodoUnion[] enthalten.

LH-CW-05: UI-Anzeige

• Im Chain Workbench Modal sollen Section-Level Issues (aus Findings) getrennt von Template-Match-Todos angezeigt werden (z. B. zuerst „Section-Level Issues“, dann „Template Matches“).

4.4 TODO-Generator und Section-Types

LH-CW-06: Section-Type-Vorschläge

• Der TODO-Generator soll bei fehlendem oder unpassendem Section-Type Vorschläge liefern (z. B. „Add Section Type: experience“), vgl. FA-PL-08.

4.5 Fix-Actions

LH-CW-07: Bestehende Fix-Actions

• Die in Chain Inspector v0.3 und im Fix-Findings-Command implementierten Actions bleiben erhalten und erweiterbar:
  • dangling_target: Create Missing Note, Retarget Link
  • dangling_target_heading: Create Missing Heading, Retarget
  • only_candidates: Promote Candidates, Create Explicit Edges
• Optional: Actions für no_causal_roles (z. B. „Edge-Type ändern“) und missing_edges („Add edges to section“) wie in 10_Workbench_Findings_Integration.md skizziert.

4.6 Command und Sichtbarkeit

LH-CW-08: Command „Mindnet: Chain Workbench (Current Section)“

• ID: mindnet-chain-workbench.
• Kontext: editorCallback.
• Verhalten: Öffnet Chain Workbench Modal mit aktuellem Report/Model.
• Optional (FA-PL-12a): Zusätzlicher Command ohne Editor, mit Notice bei fehlender Datei.

4.7 Scan Chain Gaps

LH-CW-09: Command „Mindnet: Scan Vault for Chain Gaps“

• Soll ebenfalls Notice auslösen, wenn Chain-Dictionaries fehlen; Section-Type-Logik soll bei Vault-Scan berücksichtigt werden (effective_type pro Section), sofern technisch eingebaut.

---

5. Abhängigkeiten von Parser und Mapping

5.1 Section-Parser (FA-PL-01)

• NoteSection muss erweitert werden um:
  • sectionType: string | null (aus [!section] type).
  • blockId: string | null (aus Heading ^block-id).
• Ohne diese Erweiterung kann Chain Inspector keinen Section-Type pro Section nutzen; dann bleibt nur Note-Type (bisheriges Verhalten).

5.2 Graph-Index

• buildNoteIndex nutzt splitIntoSections; sobald NoteSection.sectionType existiert, muss der Graph-Index oder eine nachgelagerte Schicht (z. B. templateMatching) pro Section den Section-Type aus den geparsten Sections auslesen und an Candidate-Nodes weitergeben.

5.3 Types-Loader (FA-PL-13)

• Optional: Validierung von Section-Types gegen types.yaml (z. B. Lint oder Hinweis im Workbench).

---

6. Nichtfunktionale Anforderungen

6.1 Performance

• Template-Matching: Max. 30 Candidate-Nodes, Backtracking für typisch ≤ 5 Slots; Top-K Matches begrenzt (z. B. 3).
• Keine Blockierung der UI; bei großen Reports ggf. asynchron oder mit Fortschrittsanzeige.

6.2 Abwärtskompatibilität

• Notes ohne Section-Types funktionieren unverändert: effective_type = noteType.
• Bestehende Chain-Templates und Chain-Roles bleiben gültig.

6.3 Dokumentation

• Benutzerhandbuch: Erklärung, dass „Inspect Chains“ und „Chain Workbench“ nur bei geöffneter Markdown-Datei in der Befehlspalette verfügbar sind.
• Dokumentation der Finding-Codes und Todo-Typen (z. B. in diesem Lastenheft oder im Konzeptdokument 03_chain_identification_and_matching.md).

---

7. Erfolgskriterien (Zusammenfassung)

• Chain Inspector: Verwendet effective_type (Section-Type oder Note-Type) für Template-Matching und Gap-Detection; Findings inkl. Section-Type-Kontext wo sinnvoll; Notice bei fehlenden Dictionaries.
• Chain Workbench: Zeigt Template-Matches und Section-Level-Todos (aus Findings); Todos enthalten Section-Type-Information für Edge-Vorschläge; Fix-Actions für die definierten Finding-Typen.
• Section-Type-Integration: Section-Parser liefert sectionType; Template-Matching und Workbench nutzen effective_type durchgängig.
• Offene Punkte aus Findings-Integration: generateFindingsTodos umgesetzt, in buildWorkbenchModel integriert, UI für globalTodos; Priorisierung/Deduplizierung wie in Umsetzungsplan geregelt.

---

8. Referenzen

• 06_LH_WP26_Plugin_Integration.md – FA-PL-08, FA-PL-12, FA-PL-12a, FA-PL-14
• WP26_Plugin_Interface_Specification.md – Abschnitte 3.4, 8.2
• 10_Workbench_Findings_Integration.md – Findings → Todos, Todo-Typen, Phasen
• CHAIN_INSPECTOR_V04_REPORT.md, CHAIN_INSPECTOR_V042_REPORT.md – Template Matching, Profiles
• 02_concepts/03_chain_identification_and_matching.md – Konzepte
• 08_Testing_Chain_Workbench.md – Testanleitung

---

Ende des Lastenhefts