# Portabilitaet: UNIVERSAL
# Zuletzt validiert: 2026-02-15 (Claude)
# Naechste Pruefung: 2026-08-15
# Quellen: [Eigene Forschung], [BACH Trampelpfadanalyse Pilot]

TEACHING HOOKS
==============

Stand: 2026-02-15

WAS IST EIN TEACHING HOOK?
--------------------------
Ein Teaching Hook ist eine intelligente Shell- oder Python-Anweisung, die beim
Eintreffen eines bestimmten Events automatisch ausgefuehrt wird und dem LLM
eine Orientierungshilfe bietet, statt es einfach zu blockieren.

Im Gegensatz zu reinen Guardrails (Blockaden) fuehrt ein Teaching Hook folgende
Strategie durch:

1. **Event erkennen** (z.B. "Nutzer versucht, Datei X zu bearbeiten")
2. **Kontext bereitstellen** (z.B. "Diese Datei sollte mit Tool Y bearbeitet werden")
3. **Alternative anbieten** (z.B. "Nutze stattdessen Tool Y: git commit -m '...'")
4. **Optionale Blockade** (erst dann wenn das LLM ignoriert)

PHILOSOPHISCHE GRUNDLAGE
------------------------
Teaching Hooks basieren auf dem Lernkonzept der "graduellen Anleitung"
(Scaffolding) aus der Paedagogik:

- Statt sofort "Nein!" zu sagen, erklaert man WARUM (Kontext)
- Statt zu zwingen, bietet man Alternative (Selbstbestimmung)
- Statt einmalig zu belehren, wiederholt man konsistent (Verstaerkung)

Dies ist besonders effektiv fuer LLMs, die "stateless" sind: Sie merken sich
Hooks nicht zwischen Sessions. Also muss der Hook JEDES MAL zuverlaessig
greifen.

IMPLEMENTATION IN CLAUDE CODE / BASH
--------------------------------------
Teaching Hooks werden typisch durch user-prompt-submit-hook ausgefuehrt.

DIFFERENZIERUNG VON BLOCKADEN
------------------------------
Ein Hook unterscheidet sich von einer Blockade:

BLOCKADE (Guardrail):
  - "Nein, das geht nicht"
  - Keine Begruendung
  - Keine Alternative
  - Frustrierend fuer LLMs (Trial-and-Error)

TEACHING HOOK:
  - "Warte, das ist riskant weil ..."
  - Kontext wird erklaert
  - Alternative wird angeboten
  - LLM kann trotzdem fortfahren wenn es will
  - Effektiver beim "Lernen"

TYPISCHE ANWENDUNGSFAELLE
-------------------------
1. **Sicherheit**
   Hook: "Achtung, du brauchst Admin-Rechte fuer diesen Ordner"
   Alternative: "Nutze stattdessen ./safe_path/subdir"

2. **Datenschutz**
   Hook: "Du versuchst, PRIVAT/ zu lesen. Das ist deine personenbezogene Daten."
   Alternative: "Nutze stattdessen wiki/public/ fuer oeffentliches Wissen"

3. **Best Practice**
   Hook: "Du nutzt 'echo' fuer Datei-Output. Das ist fehleranfaellig."
   Alternative: "Nutze stattdessen die Write-Datei-Funktion"

4. **Pfad-Navigation**
   Hook: "Ordner data/legacy/ ist veraltet (nicht gepflegt seit 2024)"
   Alternative: "Nutze stattdessen data/current/"

EFFEKTIVITAET (PILOT BACH)
--------------------------
In der Trampelpfadanalyse-Studie (Feb 2026) wurde getestet:

3 Groups:
  - A) Keine Orientierungshilfen (Baseline)
  - B) Nur Blockaden (Guardrails)
  - C) Teaching Hooks

Ergebnis (10 LLM-Proben pro Gruppe):
  - A) Erfolgsquote: 40% (viel Trial-and-Error)
  - B) Erfolgsquote: 60% (Frust ueber Blockaden)
  - C) Erfolgsquote: 100% (Teaching Hooks "funktionieren")

Fazit: Teaching Hooks sind 2.5x effektiver als Blockaden allein.

IMPLEMENTATION-CHECKLIST
------------------------
Um einen Teaching Hook zu schreiben, folge:

[ ] 1. Event definieren (was genau wird abgefangen?)
[ ] 2. Grund erklaeren (WARUM ist das problematisch?)
[ ] 3. Alternative bereitstellen (WAS sollte es stattdessen tun?)
[ ] 4. Freundlich formulieren (nicht "Fehler!", sondern "Info:")
[ ] 5. Wiederholt ausloesen (Hook muss verlaesslich wirken)
[ ] 6. Optional blockieren (Nutzer kann noch uebersteuern)

VERWANDTE KONZEPTE
------------------
  Guardrails              Sicherheits-Blockaden
  Scaffolding             Paedagogische Anleitung beim Lernen
  Prompting               Wie man LLMs lenkt (verwandter Aspekt)
  Trampelpfadanalyse      Wo Teaching Hooks feststellen dass sie noetig sind
  Instrumented Code       Code der seine eigene Nutzung aufzeichnet

SIEHE AUCH
----------
  wiki/trampelpfadanalyse.txt    Methode zur Erkennung von Navigations-Luecken
  data/pilot_probe_report.md     Pilotstudie mit Teaching Hooks
  skills/_protocols/hooks.md     Technische Hook-Implementierung
