| name | toadapt-research-methodology |
| description | Forschungs-Disziplin des ToAdapt-Projekts: Wie aus einer Ahnung ein akzeptiertes, publizierbares Ergebnis wird. Lade diese Skill, wenn du (a) eine Verbesserungs-Idee für Judge/Evaluator/Prompts/Scaffolding testen oder bewerten willst ("bringt X etwas?", "sollen wir Y ändern?"), (b) ein Experiment oder eine Messung planst (Hypothese, Metriken, Erfolgs-/Abbruchkriterien), (c) Ergebnisse berichten willst (Report, Paper-Abschnitt, Statusmeldung an die Ownerin) und wissen musst, welche Behauptungen zulässig sind und welche nicht, (d) fragst, ob eine Metrik-Verbesserung "echt" ist oder durch Auslassung lügt (Pearson r vs. Mean Diff), (e) Reproduzierbarkeit sichern musst (SHA-256-Manifeste, eingefrorene Scopes, Datenablage), oder (f) eine gescheiterte Idee sauber beerdigen willst. Keywords: Hypothese, Experiment, Evidenz, Evidenz-Bar, Alignment-Studie, Blind-Review, Pearson, MAE, Mean Diff, Kalibrierung, Publikation, Claim, Reproduzierbarkeit, Manifest, DSGVO, Prolific, Retirement, Sackgasse.
|
ToAdapt Research-Methodology — von der Ahnung zum akzeptierten Ergebnis
Wann diese Skill NICHT gilt
| Deine Frage | Richtige Skill |
|---|
| "Darf ich das überhaupt ändern? Welches Gate gilt?" | toadapt-change-control |
| "Wie rechne ich diese Analyse konkret durch (First-Principles-Methoden)?" | toadapt-proof-and-analysis-toolkit |
| "Welche offenen Forschungsfragen gibt es, wo fange ich an?" | toadapt-research-frontier |
| "Wie fixe ich konkret das q4/Bloom-6-Judge-Problem?" (executable Kampagne) | toadapt-judge-alignment-campaign |
| "Welche Tests/CI-Checks zählen als Evidenz für Code-Änderungen?" | toadapt-validation-and-qa |
| "Wie bediene ich die Forschungs-Skripte (import → export → compare)?" | toadapt-run-and-operate |
| "Wie benenne ich Reports und Pipeline-Artefakte?" | toadapt-docs-and-writing |
| "Was bedeutet Bloom / TP / Scaffolding / Canvas-Scoring?" | bwl-scaffolding-reference |
Diese Skill beantwortet: Was zählt hier als Wissen, und wie erzeugt man es, ohne
sich selbst zu belügen?
Kontext in einem Absatz (für Zero-Context-Leser:innen)
ToAdapt ist ein Transfer-Trainer für BWL-Studierende (Universität St.Gallen):
Studierende beantworten Freitext-Fragen zu AI-generierten Business-Cases, ein
LLM-Judge (LLM-as-Judge = ein Sprachmodell, das Antworten nach einer Rubric
bewertet) vergibt Punkte, eine Lehrkraft sieht die Aggregate. Die zentrale
Forschungsfrage des Projekts ist deshalb immer eine Alignment-Frage: Stimmen die
Judge-Scores mit menschlichen Lehrer-Scores überein — und unter welchen Bedingungen
nicht? Die kanonische Referenzstudie liegt in
docs/teacher_alignment_report_20260531_17submissions.md (Achtung: Dateiname sagt
"17submissions", der tatsächliche eingefrorene Scope sind 16 Submissions / 64
Frage-Zeilen — der Report selbst dokumentiert das korrekt).
1. Die Evidenz-Bar
Regel 1: EIN Mechanismus muss ALLE Beobachtungen erklären — auch die negativen.
Eine Erklärung, die nur die günstigen Datenpunkte abdeckt, ist keine Erklärung,
sondern Rosinenpickerei. Bevor du eine Behauptung als "gesichert" markierst, prüfe:
Gibt es eine Beobachtung im selben Datensatz, die der behauptete Mechanismus NICHT
erklärt? Dann ist entweder der Mechanismus falsch oder unvollständig.
Das Lehrstück des Projekts (Stand: 2026-07-08, Quelle:
docs/teacher_alignment_report_20260531_17submissions.md):
Die Kalibrierung des Judges (case-spezifische Kalibrierungsanker pro Frage — seit 2026-07-09 im Case-JSON statt hartkodiert, siehe
_format_calibration_notes in backend/evaluator/rubric_evaluator.py, Commit
9a8077f "human alignment with teacher scores") veränderte die Metriken so:
| Metrik | Vor Kalibrierung | Nach Kalibrierung | Lesart |
|---|
| Pearson r | 0.631 | 0.796 | besser (Rangordnung stimmt öfter) |
| MAE (Punkte) | 2.984 | 2.711 | leicht besser |
| RMSE (Punkte) | 4.626 | 3.897 | besser |
| Mean Diff (Judge − Teacher) | −0.234 | −2.07 | schlechter: systematischer Bias |
| "Teacher höher" (n von 64) | 28 | 48 | Judge unterbewertet jetzt in 48/64 Fällen |
Wer nur "Pearson r stieg von 0.63 auf 0.80" berichtet, lügt durch Auslassung.
Die Kalibrierung machte den Judge korrelierter UND systematisch strenger. Beides
ist dasselbe Ergebnis; nur beides zusammen ist die Wahrheit. Konsequenz für jede
Messung in diesem Projekt:
- Berichte IMMER Korrelation (Pearson r) und Bias (Mean Diff) und
Fehlergröße (MAE/RMSE) und die Verteilung (wer liegt öfter höher, n).
- Berichte IMMER pro Frage aufgeschlüsselt, nicht nur aggregiert: Der Aggregat-MAE
von 2.711 versteckt, dass q4 (Bloom-6-Integrationsfrage, 30 Punkte) mit MAE ~4.97
die Schwachstelle ist, während q1–q3 bei MAE 1.2–2.5 liegen.
- Das Vergleichs-Skript
scripts/compare_teacher_rubric_scores.py liefert all das
bereits (pearson_r, mae_points, rmse_points, mean/median diff, within_1pt/2pt/
10pctpts, Per-Frage-Blätter). Nutze es. Erfinde keine eigene Metrik-Auswahl.
Regel 2: Jede Behauptung bekommt einen zugewiesenen adversarialen
Widerlegungsversuch, BEVOR sie gilt.
Prozedur (Solo-Projekt, also selbst durchführen, aber schriftlich):
- Formuliere die Behauptung als einen Satz ("Änderung X verbessert Y").
- Schreibe die stärkste dir bekannte Gegenerklärung auf ("Y stieg, weil sich
gleichzeitig Z änderte / weil der Scope anders geschnitten ist / weil n zu
klein ist / Regression zur Mitte").
- Führe mindestens EINEN gezielten Check aus, der die Gegenerklärung bestätigen
würde, wenn sie stimmt (z. B. gleiche Analyse auf identischem Scope, Blick auf
die Metrik, die sich verschlechtert haben müsste).
- Erst wenn der Check die Gegenerklärung NICHT bestätigt, darf die Behauptung in
einen Report. Dokumentiere den Widerlegungsversuch im Report ("Geprüfte
Alternativerklärungen: …").
2. Hypothese sagt Zahlen voraus — VOR dem Lauf
Eine Hypothese ohne vorhergesagte Zahl ist eine Meinung. Fülle dieses Template aus
und speichere es (z. B. als Notiz im Experiment-Branch oder im Report-Entwurf),
BEVOR du das Experiment startest — sonst passt du nachträglich die Erfolgskriterien
an das Ergebnis an (HARKing, "Hypothesizing After the Results are Known").
Template:
## Hypothese <kurzer Name> — <Datum>
Behauptung (1 Satz):
Mechanismus (warum sollte das funktionieren?):
Datensatz + Scope (eingefroren, mit n):
Primärmetrik + vorhergesagter Wert/Bereich:
Nebenmetriken, die sich NICHT verschlechtern dürfen (Schwellen!):
Abbruchkriterium (wann gilt die Hypothese als widerlegt?):
Stärkste Alternativerklärung + geplanter Check dagegen:
Kosten des Laufs (LLM-Calls, Zeit):
Ausgefülltes Beispiel (nachgestellt an der realen Kalibrierungsstudie vom
2026-05-31 — so hätte das Blatt VOR dem Lauf aussehen müssen):
## Hypothese kalibrierungsanker-v1 — 2026-05-31
Behauptung: Fragen-spezifische Kalibrierungsanker im Judge-Prompt erhöhen die
Übereinstimmung mit Lehrer-Scores.
Mechanismus: Die Anker kodieren, was die Lehrkraft im Blind-Review tatsächlich
bestraft/belohnt hat (z. B. "nur eine Herausforderung begrenzt den Score").
Datensatz + Scope: Blind-Review-Workbook, 16 vollständige Submissions,
64 Frage-Zeilen (q1–q4 je 16). Scope eingefroren, Join über review_item_id.
Primärmetrik: Pearson r gesamt steigt von 0.63 auf ≥ 0.75.
Nebenmetriken (dürfen nicht kippen): |Mean Diff| bleibt ≤ 1.0 Punkt;
MAE pro Frage steigt nirgends um > 0.5.
Abbruchkriterium: r < 0.65 ODER |Mean Diff| > 2.0 → Anker verwerfen/überarbeiten.
Alternativerklärung: r steigt nur, weil der Judge global strenger wird und die
Rangordnung dadurch zufällig stabiler aussieht. Check: Mean Diff + "Teacher
höher n" vor/nach vergleichen.
Kosten: 64 Judge-Calls (Rescore des eingefrorenen Scopes).
Mit diesem Blatt wäre das reale Ergebnis (r 0.796 ✓, aber Mean Diff −2.07 ✗)
automatisch als Teilerfolg mit verletzter Nebenbedingung klassifiziert worden —
genau das ist der heutige, ehrliche Projektstand: Der systematische Streng-Bias ist
das offene Problem, nicht ein Fußnotendetail.
3. Idee-Lebenszyklus
Jede Idee durchläuft diese Stationen. Keine Abkürzungen — insbesondere nicht von
"Idee" direkt zu "auf main deployen".
Idee
→ Klassifikation (toadapt-change-control: welche Änderungsklasse, welches Gate?)
→ Hypothese-Blatt (Abschnitt 2 dieser Skill, VOR dem Lauf)
→ Experiment (lokal oder Branch — NIE direkt am produktiven Judge)
→ Messung (toadapt-proof-and-analysis-toolkit; Vergleichs-Pipeline unten)
→ Adoption (Gate aus change-control erfüllt, Report geschrieben)
ODER
dokumentiertes Retirement (Eintrag im Stil von toadapt-failure-archaeology:
Symptom → Root Cause → Beleg → Status "verworfen, weil …")
Regeln zu den Stationen:
-
Experiment nie am Prod-Judge: Änderungen an EVALUATOR_SYSTEM,
EVALUATE_PROMPT oder den Kalibrierungsankern (backend/evaluator/ rubric_evaluator.py) werden lokal bzw. auf einem Branch gegen den
eingefrorenen Blind-Review-Scope gerechnet, bevor irgendetwas deployt wird.
Das Gate selbst ("kein Judge-Deploy ohne Alignment-Recheck") gehört
toadapt-change-control; diese Skill liefert die Methodik dafür.
-
Messung heißt: die bestehende Pipeline benutzen (Bedienung im Detail:
toadapt-run-and-operate):
python scripts/import_prolific_runs.py <export-datei-oder-ordner> --batch <name>
python scripts/export_review_workbooks.py --prefix <experiment-name>
python scripts/compare_teacher_rubric_scores.py \
--teacher-workbook <blind-ausgefüllt.xlsx> \
--rubric-workbook <rubric.xlsx>
-
Sackgassen sind Ergebnisse. Eine widerlegte Hypothese wird NICHT gelöscht,
sondern mit Hypothese-Blatt + Messwerten + Verwerfungsgrund abgelegt (Eintrag in
toadapt-failure-archaeology bzw. deren Chronik-Format). Sonst schlägt die
nächste Person dieselbe Schlacht noch einmal.
4. Woher gute Ideen hier historisch kamen
Prüfe neue Ideen gegen diese Herkunftsmuster — sie sind die empirisch belegten
Quellen echter Verbesserungen in diesem Repo:
| Quelle | Beispiel im Repo | Beleg |
|---|
| Blind-Review-Empirie (was Lehrende real bestrafen/belohnen) | Kalibrierungsanker q1–q4 im Judge-Prompt — direkt aus Lehrer-Rationales destilliert | Commit 9a8077f; heute als calibration_notes im Golden-Case-JSON (zweistufig mit BLOOM_CALIBRATION_ANCHORS) |
| Deploy-Schmerz (wiederholtes Blind-Debugging) | /health/diagnostics-Endpoint entstand aus der Mongo-Debugging-Saga gegen Railway | Commits 464bbca ("Expose Mongo env diagnostics"), dbc92f2 |
| Lehrpersonen-Feedback (Unterstützungs-Doktrin) | Review-Flags (needs_human_review) als explizite "hier soll ein Mensch draufschauen"-Signale | Report-Schlusssatz: "Review-Flags markieren Stellen, an denen der Judge die Lehrkraft unterstuetzen und nicht ersetzen soll." |
Anti-Quelle: Framework-Moden. "Lasst uns Agent-Framework X / Prompt-Technik Y
einbauen, weil es gerade alle tun" hat in diesem Repo keine einzige belegte
Verbesserung erzeugt — wohl aber teure Umbauten (siehe die WebSocket- und
SDK-Wechsel-Kapitel in toadapt-failure-archaeology). Eine Idee, die nicht an
einer konkreten Beobachtung (Datenpunkt, Schmerz, Feedback) hängt, bekommt kein
Hypothese-Blatt und keinen Lauf.
5. Publikations- und Claim-Standard
Was behauptet werden DARF
- Nur blind validierte Metriken, immer mit Scope-Angabe n. Korrekt: "Auf dem
eingefrorenen Blind-Review-Scope (16 Submissions, 64 Frage-Zeilen, Stand
2026-05-31) erreicht der kalibrierte Judge Pearson r = 0.796 bei MAE 2.711 und
systematischer Unterbewertung (Mean Diff −2.07; Teacher höher in 48/64 Fällen)."
"Blind" heißt: Die Lehrkraft vergab ihre Punkte im Blind-Workbook, OHNE die
Judge-Scores zu sehen (das Blind-Workbook enthält per Konstruktion keine
Judge-Spalten — prüfbar in
_write_blind_workbook,
scripts/export_review_workbooks.py).
- Beschreibungen des Systems und der Methodik (Architektur, Blind-Review-Protokoll,
konservativer Judge mit Review-Flags) — als Design-Beitrag, nicht als
Wirksamkeitsbeweis.
Was NICHT behauptet werden darf
| Verbotener Claim | Warum |
|---|
| "ToAdapt verbessert Lernleistung / Transferkompetenz" | Keine Kontrollgruppe, kein Prä-Post-Design. Wirksamkeits-Claims erfordern ein kontrolliertes Studiendesign, das es (Stand: 2026-07-08) nicht gibt. |
| "Der Judge ersetzt die Lehrkraft" / "automatisiertes Grading" | Projektdoktrin ist unterstützen, nicht ersetzen — im Judge-System-Prompt kodiert ("Du unterstützt Lehrende bei der Bewertung", EVALUATOR_SYSTEM in backend/evaluator/rubric_evaluator.py) und im Alignment-Report festgehalten. Review-Flags + konservative Punktvergabe sind Feature, nicht Schwäche. |
| Aggregat-Metriken ohne die Gegenmetrik (nur r ohne Mean Diff, nur MAE ohne Per-Frage-Split) | Lüge durch Auslassung — siehe Abschnitt 1. |
| Zahlen aus nicht eingefrorenen / nachträglich umgeschnittenen Scopes | Scope-Shopping macht jede Metrik manipulierbar. |
| Irgendetwas unter Nennung echter Teilnehmer-IDs oder -Antworten | PII (personenbezogene Daten); siehe unten. |
Reproduzierbarkeit — die vier Anker
- SHA-256-Manifeste beim Import.
scripts/import_prolific_runs.py kopiert
Rohdaten nach data/prolific_runs/raw/<batch>/ und schreibt
data/prolific_runs/manifests/<batch>.json mit Dateiliste, Größen und
SHA-256-Hash pro Datei. Das Skript verweigert Überschreiben existierender
Batches (FileExistsError) — Batches sind append-only. So ist später beweisbar,
auf welchen Bytes eine Analyse lief.
- Eingefrorene Scopes mit stabilen IDs. Jede Frage-Zeile hat eine
review_item_id im Format {case_id}:{question_id}:{nnn} (dreistellig
laufend, erzeugt in scripts/export_review_workbooks.py). Der Vergleich joint
ausschließlich über diese IDs; das Lehrer-Workbook ist kanonisch —
Rubric-Zeilen ohne Lehrer-Match werden by design ausgeschlossen (verhindert,
dass bereinigte Testuser zurück in die Analyse rutschen; dokumentiert im
Docstring von scripts/compare_teacher_rubric_scores.py).
- Benennung und Zeitstempel. Alle Pipeline-Artefakte tragen UTC-Timestamps
(
YYYYMMDDTHHMMSSZ) im Dateinamen; Details und Report-Namenskonventionen:
toadapt-docs-and-writing.
- Daten bleiben privat.
data/prolific_runs/** ist per Root-.gitignore
vollständig von Git ausgeschlossen (nur das README ist getrackt). Echte
Teilnehmerdaten liegen seit 2026-07-08 AUSSERHALB des Repos unter
~/ToAdapt_sensitive_data/ und werden NIEMALS zurückkopiert, committet oder
in Skills/Fixtures zitiert (DSGVO- und Prolific-ToS-Pflichten; Hintergrund des
PII-Vorfalls: toadapt-failure-archaeology). Für Tests und Beispiele:
ausschließlich synthetische Daten.
Achtung, echter LLM-Verbrauch: scripts/retry_technical_fallback_scores.py
macht ohne --dry-run echte Judge-Calls. In der Planung eines Laufs als Kosten
budgetieren (Hypothese-Blatt, Feld "Kosten des Laufs").
6. Wohin mit konkreten Forschungsfragen
Diese Skill definiert die Disziplin. Die konkreten offenen Probleme (mit
SOTA-Lücke, vorhandenen Projekt-Assets, ersten Schritten und falsifizierbaren
Meilensteinen) leben in toadapt-research-frontier. Das härteste lebende Problem —
systematische q4/Bloom-6-Unterbewertung (MAE ~4.97 auf dem 64-Zeilen-Scope) — hat
eine eigene executable Kampagne: toadapt-judge-alignment-campaign.
Provenance und Wartung
Erstellt: 2026-07-08, verifiziert gegen den Repo-Stand desselben Tages
(Branch main, HEAD 141bb63, nach dem filter-repo-Rewrite vom 2026-07-08).
Re-Verifikations-Kommandos für drift-anfällige Fakten (vom Repo-Root ausführen):
| Fakt | Kommando |
|---|
| Alignment-Report existiert, Scope 16/64 | grep -n "Eindeutige Submissions|Teacher-Items" docs/teacher_alignment_report_20260531_17submissions.md |
| Metriken r/MAE/MeanDiff vor→nach | grep -n "Pearson r|Mean Diff|MAE" docs/teacher_alignment_report_20260531_17submissions.md |
| Kalibrierung zweistufig (Case-Anker vor Bloom-Generik) | grep -n "calibration_notes|BLOOM_CALIBRATION_ANCHORS" backend/evaluator/rubric_evaluator.py | head |
| Unterstützen-nicht-ersetzen im Judge-Prompt | grep -n "Du unterstützt Lehrende" backend/evaluator/rubric_evaluator.py |
| SHA-256-Manifest im Import-Skript | grep -n "sha256|manifest" scripts/import_prolific_runs.py |
| review_item_id-Format | grep -n "review_item_id = f" scripts/export_review_workbooks.py |
| Lehrer-Workbook kanonisch / Rubric-only ausgeschlossen | sed -n '1,6p' scripts/compare_teacher_rubric_scores.py |
| Blind-Workbook ohne Judge-Spalten | grep -n -A 14 "def _write_blind_workbook" scripts/export_review_workbooks.py |
| data/prolific_runs gitignored | grep -n "prolific" .gitignore |
| retry-Skript macht echte LLM-Calls | sed -n '1,2p' scripts/retry_technical_fallback_scores.py && grep -n "dry-run" scripts/retry_technical_fallback_scores.py |
| Ideen-Herkunfts-Commits existieren | git log --oneline --all | grep -E "9a8077f|464bbca" |
| Sensible Daten außerhalb des Repos | ls ~/ToAdapt_sensitive_data |
Update 2026-07-09 (HEAD 64b62f9): Kalibrierungsanker-Verweise auf das zweistufige Modell (Case-JSON vor Bloom-Generik) aktualisiert.
