mindnet/docs/archiv/Überarbeitungshinweise_WP03.md

mindnet v2 — Dokumentationsreview (vollständig & konsolidiert)

Dieses Dokument fasst alle notwendigen Anpassungen der mindnet-v2 Dokumentation zusammen.
Der Fokus liegt ausschließlich auf Aspekten, die durch die aktuellen Arbeiten verändert wurden:

• neue Edge-Mechanik
• neuer Importer
• neues Verhalten von note_payload & chunk_payload
• Default-Typregeln aus types.yaml
• Inline- und Callout-Relations
• WP04a – Einführung der Retriever-Schicht
• neue Diagnose- und Testskripte

Es handelt sich um eine strukturelle Analyse.
Nichts davon überschreibt bestehende Inhalte — es markiert nur, was angepasst werden muss.

---

1) knowledge_design.md

Erforderliche Anpassungen

1.1 Neue Edge-Arten dokumentieren

Es müssen vier neue Kategorien beschrieben werden:

1. Inline-Edges

   Beispiel:
   [ [rel:depends_on Embeddings 101] ]
   (Leerzeichen hier zur Demonstration; im echten Dokument ohne Leerzeichen)

2. Callout-Edges

    > [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
   

3. Typbasierte Default-Kanten
   Aus types.yaml → edge_defaults

4. Strukturkanten

   • belongs_to
   • next
   • prev

1.2 Neue Edge-Felder ergänzen

Jeder Edge enthält jetzt:

• rule_id
• confidence
• scope = "chunk"
• deterministischer edge_id

Diese Felder müssen vollständig erklärt werden.

1.3 Chunk-basierte Kanten

Neu: Alle Kanten entstehen ausschließlich zwischen Chunks, nie zwischen Notes.
Notes dienen nur noch als Metadatencontainer.

---

2) TYPE_REGISTRY_MANUAL.md

Erforderliche Anpassungen

2.1 Typauflösung dokumentieren

Die Regeln sind jetzt:

• Typ aus Frontmatter → höchste Priorität
• Falls nicht gesetzt: Typ aus Dateipfad ableiten
• Falls unbekannt: Fallback auf types.default
• Typ definiert:
  • retriever_weight
  • chunk_profile
  • edge_defaults

Diese müssen klar dokumentiert werden.

2.2 Neue Fallback-Regeln

Wenn Werte fehlen, werden sie ersetzt durch:

    types.default.retriever_weight
    types.default.chunk_profile
    types.default.edge_defaults

2.3 Beispiele aktualisieren

Alle Beispiele müssen auf die neue Inline-Syntax angepasst werden.

---

3) wp04_retriever_scoring.md

Erforderliche Anpassungen

3.1 Neue Scoring-Formel

    total_score =
        semantic_weight   * semantic_score
      + edge_weight       * edge_bonus
      + centrality_weight * centrality_bonus
      + type_weight       * retriever_weight

3.2 Bedeutung von confidence

confidence wirkt multiplikativ bei edge_bonus.
Inline > Callout > Default (Standardwerte im Code hinterlegt).

3.3 Pfadbegründungen

Der Retriever gibt optional paths[] zurück:

    paths: [
        {
            "via": "depends_on",
            "confidence": 0.7,
            "hops": ["Note A", "Chunk A#01", "Note B"]
        }
    ]

Diese Funktion müssen dokumentiert werden.

---

4) mindnet_v2_implementation_playbook.md

Erforderliche Anpassungen

4.1 Neuer Import-Prozess vollständig dokumentieren

Der Importer läuft jetzt so:

1. Markdown lesen

2. Frontmatter extrahieren

3. Typauflösung via types.yaml

4. Note-Payload generieren

5. Chunking anwenden

6. Inline-Kanten finden

7. Callout-Kanten finden

8. Default-Edges erzeugen

9. Strukturkanten erzeugen

10. Chunks in Qdrant upserten

11. Edges upserten

12. Diagnose laufen lassen:

    python3 -m scripts.payload_dryrun
    python3 -m scripts.edges_full_check
    

4.2 Erweiterte Testpipeline

Neu zu dokumentieren:

    tests.test_edges_all
    scripts.edges_full_check
    scripts.payload_dryrun

Diese Testschritte sind jetzt Standardanforderung nach jeder Änderung.

---

5) mindnet_technical_architecture.md

Erforderliche Anpassungen

5.1 Aktualisiertes Schema für Qdrant Collections

Notes:

    note_id
    title
    type
    fulltext
    retriever_weight
    chunk_profile
    edge_defaults
    tags
    updated

Chunks:

    chunk_id
    note_id
    text
    window
    ord
    retriever_weight
    chunk_profile
    neighbors_prev
    neighbors_next

Edges:

    edge_id
    source_id
    target_id
    kind
    scope = "chunk"
    rule_id
    confidence

5.2 Dokumentation der Edge-Pipeline

Neu beschreiben:

• Inline-Parser
• Callout-Parser
• Default-Edge-Resolver
• Strukturkanten
• Normalisierung für Qdrant
• deterministische ID-Bildung

---

6) mindnet_functional_architecture.md

Erforderliche Anpassungen

6.1 Inline-Relations – einzig gültige Syntax

Nur diese Syntax erzeugt Kanten:

    [[rel:depends_on Embeddings 101]]

Nicht unterstützt:

    rel:depends_on [[Embeddings 101]]

Dies muss klar dokumentiert werden.

6.2 Prioritäten der Kantenerzeugung

Gültige Reihenfolge:

1. Inline
2. Callout
3. Typdefaults
4. Strukturkanten

6.3 Relaunch der Chunk-zentrierten Funktionslogik

Alle Beispiele müssen angepasst werden.

---

7) chunking_strategy.md

Erforderliche Änderungen

7.1 Neues Verhalten der Chunks

• ord ist jetzt Sortierkriterium
• window wird über chunk_config erzeugt
• Chunkprofile kommen ausschließlich aus types.yaml

7.2 Best Practices erneuern

Empfehlung:

• keine manuelle Chunkprofile mehr im Frontmatter setzen

---

8) docs_mindnet_retriever.md

Erforderliche Änderungen

8.1 Neue Ausgabeparameter dokumentieren

Retriever liefert jetzt:

    semantic_score
    edge_bonus
    centrality_bonus
    type_score
    total_score
    paths[]

8.2 Graph-Expansion

Dokumentieren:

• Seed-Auswahl
• Depth-Limit
• Edge-Filterung
• Wirkung von confidence auf edge_bonus

---

9) Handbuch.md

Erforderliche Änderungen

9.1 Neuer Import-Workflow

Erläuterung der Parser:

• Inline-Parser
• Callout-Parser
• Default-Kanten
• Struktur-Kanten

9.2 Best Practices

Ergänzen:

• Typenpflege erfolgt nur in types.yaml
• Tests immer nach Änderungen ausführen

---

Gesamtübersicht der notwendigen Anpassungen

Dokument	Anpassungsbedarf
knowledge_design.md	neue Edge-Arten, Felder, Chunk-Edges
TYPE_REGISTRY_MANUAL.md	Typauflösung, neue Felder, neue Fallbacks
wp04_retriever_scoring.md	neue Score-Formel, Pfade, confidence
implementation_playbook.md	neuer Importprozess, Tests
technical_architecture.md	aktualisierte Schemas
functional_architecture.md	Syntax + Prioritäten
chunking_strategy.md	ord, window, neue Profile
docs_mindnet_retriever.md	neue API-Parameter
Handbuch.md	Parser + Best Practices

---

Empfehlung zur Umsetzung

1. Dieses Review-Dokument als Master-Referenz verwenden.

2. Jedes Dokument strikt nur an den beschriebenen Stellen anpassen.

3. Überprüfen, ob Wann/Wo Typen, Kanten und Parser erklärt werden.

4. Nach jeder Anpassung Testlauf:

    python3 -m scripts.payload_dryrun
    python3 -m scripts.edges_full_check
   

5. Danach Playbook + Programmplan updaten.