# Portabilität: UNIVERSAL
# Zuletzt validiert: 2026-02-08 (Sonnet 4.5)
# Nächste Prüfung: 2026-04-08
# Ressourcen: [memory_lessons table, hub/lesson.py, bach_api.lesson]

LESSONS LEARNED - Wissensmanagement
====================================

STAND: 2026-02-08

System zum Erfassen und Abrufen von Erkenntnissen, Bug-Fixes und Best Practices.
Lessons sind der Kern des "Rückflusses" in das Systemverhalten.

CLI-BEFEHLE
-----------
  bach lesson add "Titel: Lösung"     Neue Lesson hinzufügen
  bach lesson edit ID [Optionen]       Lesson bearbeiten (v1.1.70)
  bach lesson deactivate ID [-r REASON] Deaktivieren (v1.1.70)
  bach lesson last [n]                 Letzte n Lessons (Standard: 5)
  bach lesson search "keyword"         Durchsuchen
  bach lesson show ID                  Details & Metadaten anzeigen

LIBRARY API
-----------
  from bach_api import lesson
  lesson.add("Titel: Lösung", "--category", "bug")
  lesson.list("bug")
  lesson.edit(42, "--title", "Neuer Titel")
  lesson.deactivate(42, "--reason", "Obsolet")
  lesson.show(42)

KATEGORIEN (Aktuell)
--------------------
  bug           Bug-Fixes und Workarounds
  workflow      Erweiterte Arbeitsabläufe (z.B. Multi-LLM)
  tool          Tool-spezifisches Wissen
  integration   Integration mit externen Systemen
  performance   Performance-Optimierungen
  general       Allgemeine Architektur-Entscheidungen

SCHWEREGRADE
------------
  low           Nur zur Info
  medium        Empfohlener Standard
  high          Wichtige Regel (Injektor-Prio)
  critical      Kritisches Systemwissen (Schutzregeln)

BEISPIELE
=========

  # Bug-Fix dokumentieren
  bach lesson add "SQLite Lock: WAL-Mode aktivieren" --category bug --severity high

  # Workflow dokumentieren
  bach lesson add "Multi-LLM: Immer llm lock vor Schreibzugriff" --category workflow

  # Performance-Optimierung
  bach lesson add "DB-Queries: Index auf created_at" --category performance

  # Integration-Wissen
  bach lesson add "OCR: Tesseract braucht PATH-Variable" --category integration

  # Lesson bearbeiten
  bach lesson edit 42 --title "Neuer Titel" --severity critical

  # Lesson deaktivieren
  bach lesson deactivate 42 --reason "Durch bessere Lösung ersetzt"

BEKANNTE PROBLEME & LOESUNGEN (Auszug)
=====================================

1. MULTI-LLM SHARED FILES (workflow)
   Problem: Race Conditions bei gleichzeitiger Bearbeitung.
   Lösung: IMMER `bach llm lock <datei>` vor Schreibzugriff nutzen.

2. CLI-FIRST PRINZIP (workflow)
   Problem: Manuelle Datei-Edits umgehen Injektoren/Monitoring.
   Lösung: Alles was via CLI geht (task, lesson, mem) IMMER via CLI tun.

3. WINDOWS ENCODING (bug)
   Problem: Emojis crashen oft die Standard-Windows-Konsole.
   Lösung: In Python `io.TextIOWrapper` mit UTF-8 Fallback für stdout nutzen.

4. DB-DATEI SPERREN (performance)
   Problem: Lock-Fehler bei parallelem Zugriff vieler Prozesse.
   Lösung: Kurze Transaktionen und WAL-Mode (Write-Ahead Logging).

5. DOCS-UPDATE (bug)
   Problem: Veraltete Versionen in SKILL.md blockieren Sessions.
   Lösung: `python tools/doc_update_checker.py` regelmäßig laufen lassen.

INTEGRATION
-----------
Lessons fließen automatisch in das **Dynamic Learning System** ein:
- Trigger-Generierung: Keywords in Titeln erzeugen Injektor-Hinweise.
- Aktivierung: `is_active=1` steuert, welche Regeln dem LLM präsentiert werden.

SIEHE AUCH
----------
  docs/help/memory.txt            Cognitive Memory Model
  docs/help/consolidation.txt     Vom Ereignis zur Lektion
  ROADMAP.md                 Phasen der Entwicklung
