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**