discovery-loop-init

name	discovery-loop-init
description	Initialisiert die RAG-Discovery-Schleife - fragt nach dem Datenpfad, untersucht den Bestand, fuellt SYSTEM-INPUT-SYSTEM-GOAL.md, zieht den Korpus und erzeugt den Q&A-Katalog (Train+Test). Aufrufen bevor loop.sh das erste Mal startet.

discovery-loop-init

Du richtest die Discovery-Schleife in diesem Repo ein. Am Ende muss ./loop.sh --dry-run ohne Fehler durchlaufen.

1. Frage den Menschen — nur das Nötigste

Stelle eine Frage (AskUserQuestion oder direkt): Wo liegen die Daten, über die gesucht werden soll? (Ordnerpfad, wird rekursiv gelesen.)

Alles andere hat Defaults und wird NICHT abgefragt, außer der Mensch spricht es von sich aus an:

Feld	Default	Bedeutung
q-a-path	null	vorhandene Q&A-Datei; wenn angegeben, daraus lesen statt generieren
q-a-generate	true	Fragenkatalog aus den Daten erzeugen
q-a-number	50	je Split: N Übungs- und N Prüfungsfragen

Prüfe, dass der Pfad existiert und Dateien enthält. Trage dann den YAML-Kopf von SYSTEM-INPUT-SYSTEM-GOAL.md ein (die Datei existiert schon als Template — nur den Kopf und die markierten <!-- -->-Stellen füllen, den Rest stehen lassen).

2. Untersuche den Bestand

Bevor du irgendetwas generierst: verschaffe dir ein Bild (nur lesend!).

• Formate und Mengen: find <daten> -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn
• Größenverteilung, Unterordner-Struktur, Sprachen (Stichproben lesen)
• Besonderheiten, die Retrieval schwer machen: gescannte PDFs ohne Textebene (pdftotext liefert nichts), große Tabellen, Dubletten, sehr ähnliche Massendateien vs. Exoten

Schreibe den Befund kompakt in Abschnitt 2 von SYSTEM-INPUT-SYSTEM-GOAL.md (Tabelle: Quelle/Format, Umfang, was drin steckt). Ergänze in Abschnitt 5 datenspezifische offene Fragen (z.B. "brauchen die gescannten PDFs OCR?", "zerreißt Chunking die Preistabellen?").

Leck-Prüfung (Pflicht): Liegt im Datenbestand eine Datei, die Testfragen MIT Antworten enthält (eine Kunden-Mail, ein Q&A-Duplikat, ein alter Testkatalog)? Dann: (a) im SYSTEM-INPUT als „nie Gold-Quelle" markieren, (b) dem Menschen den Ausschluss aus dem Korpus vorschlagen. Erfahrung: so eine Datei gewinnt sonst jede Retrieval-Runde und der spätere Antwort-Assistent zitiert die Testfragen statt der echten Dokumente.

3. Ziehe den Korpus

uv sync
uv run lib/select_corpus.py --seed 42 --dry-run   # erst ansehen
uv run lib/select_corpus.py --seed 42             # dann schreiben

Prüfe die Familienverteilung im Output: dominiert eine Massenquelle alles, sag es dem Menschen und schlage eine Anpassung von family_key() vor — ändern nur mit seinem OK (lib/ gehört dem Menschen).

4. Erzeuge den Q&A-Katalog (lib/questions.yaml)

Wenn q-a-path gesetzt ist: lies die Datei und übersetze sie ins Format unten. Fehlen Gold-Dateien oder Fakten, ergänze sie aus dem Bestand und markiere Unsicheres als Frage an den Menschen.

Wenn q-a-generate: true: erzeuge q-a-number Übungs- und q-a-number Prüfungsfragen aus dem Datenbestand. Vorgehen:

1. Wähle sehr verschiedene Dateien mit sehr verschiedener Inhaltsstruktur: Fließtext, Tabellen, Listen, gescannte PDFs, kurze Exoten, Massendateien, verschiedene Sprachen, verschiedene Unterordner. Nicht 100 Fragen über dieselben 10 bequemen Dateien.

2. Schlage dem Menschen erst die Frage-Kategorien vor (je mit art-Etikett: satz / wert / intervall / ocr / prozedur / aggregat / quervergleich) und kurz, wie viele Fragen je Kategorie. Diskutiere das kurz — dann generiere.

   Pflicht-Familien (Erfahrung: ein Katalog nur aus direkten Fragen ist nach 1–2 Iterationen gesättigt — Champion 1,0 — und misst nichts mehr):

   • Paraphrasen ohne Wortüberlappung: gleiche Antwort, null gemeinsames Vokabular mit dem Dokument („Abstand Drückernuss–Stulp" statt „Dornmaß", Alltagsbegriff statt Norm-Name). Der ehrliche Semantik-Test.
   • Tippfehler & phonetische Fehlschreibungen („Venuri-Dose", „Magnetfuter", „Duns-Numer") — im echten Betrieb SEHR häufig; die Frage trägt den Fehler, die Fakten stehen korrekt im Gold-Dokument.
   • Cross-Dokument (gold_alle): Antwort wächst erst aus zwei Dokumenten zusammen. Brücken findest du per Nummern-Sweep: welche Produkt-/ Bestellnummern tauchen in ≥2 Dokumenten auf (FAQ↔Katalog, Anleitung↔Katalog)?
   • Tabellenfallen: nach einem Wert mit ANDEREM Wort/Einheit als dem Spaltenkopf fragen („mit wie viel Newton packt er zu" vs. Spalte „Greifkraft F").
   • Situativ/mehrstufig: Problembeschreibung statt Suchbegriff („springt alle paar Sekunden von selbst wieder an").

3. Jede Frage braucht:

   • id — kurz, sprechend, eindeutig
   • frage — natürliche Sprache, wie ein echter Nutzer fragt (NICHT die Formulierung des Dokuments abschreiben — sonst misst du nur Wortgleichheit)
   • gold_files (EINE genügt) oder gold_alle (JEDE wird gebraucht)
   • fakten — 1–4 Zeichenketten, die wörtlich im Gold-Dokument stehen (check_questions.py prüft das, mit OCR)
   • split — hälftig uebung / pruefung, innerhalb jeder Kategorie hälftig, damit die Prüfungsmenge nicht strukturell leichter ist

4. Kopf der Datei:

k: 5
ziel: 0.85
mindestens: 0.5

questions:
  - id: beispiel-01
    frage: "..."
    gold_files: ["pfad/relativ/zur/datenwurzel.pdf"]
    fakten: ["wörtliches Zitat 1", "Zahl 2"]
    split: uebung
    art: wert

5. Validiere: uv run lib/check_questions.py — jeder Fakt muss in einer Gold-Quelle stehen. Iteriere, bis es grün ist. Danach uv run lib/select_corpus.py --seed 42 erneut (jetzt zwingt es die Gold-Dateien in den Korpus).

Wichtig: Nach der Generierung liest niemand mehr lib/questions.yaml — nicht der Planer, nicht die Experimente (Schummelprüfung in score.py erzwingt das). Sie ist das Messgerät.

5. Abschluss

uv run pytest                 # Maschinerie grün?
./loop.sh --dry-run           # Startbereitschaft
git add -A && git commit -m "init: Discovery-Schleife für <daten> eingerichtet"

(Falls noch kein git-Repo: erst git init -b main.)

Berichte dem Menschen zum Schluss:

• Datenbefund in 3 Sätzen (Formate, Mengen, Fallstricke)
• Korpus: N Dateien aus M Familien
• Katalog: N Übung + N Prüfung, Kategorien mit Anzahl
• Startkommando: ./start.sh -n 3 (überlebt Sitzungsende) oder ./loop.sh -n 3
• Zuruf-Kanal: HINTS-WHILE-RUNNING.md