# 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_`, `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`. **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**