---
type: skill
agent_ready: true
schema_version: 1
bundle_version: "0.28.0"
name: reflector
description: "Zweite Schicht der Karpathy-Compiler-Kette (raw → wiki → index → runtime). Liest abgeschlossene Session-Logs und destilliert Lektionen, Fakten, Regeln, Muster und Fragen als Vorschläge in eine Staging-Datei. Einsetzen wenn 'reflector', 'destilliere', 'destillation' oder 'aus Session-Logs lernen' erwähnt wird."
tags:
  - skill
  - second-brain
  - reflector
  - karpathy
  - staging-layer
scope: vault
bundle_skill: true
default_active:
  allgemein: true
  karpathy: true
depends_on: [session-log]
conflicts_with: []
created: 2026-05-12
updated: 2026-05-13
---

# reflector

Der `processed: false`-Marker ist die Idempotenz-Schranke: jedes Session-Log wird genau einmal destilliert, danach auf `processed: true` gesetzt. Vorschläge landen in der Staging-Datei und warten dort auf den Curator. Niemals werden Wiki-Dateien direkt beschrieben.

**Der Reflector schreibt niemals in Wiki-Dateien.** Sein einziger Output ist die Staging-Datei plus das `processed`-Flag in den gelesenen Session-Logs. Das ist Karpathys Autonomy-Slider-Prinzip in Aktion: Level 1, jeder Vorschlag braucht eine Bestätigung in der nächsten Schicht.

## Arbeitsteilung LLM vs. Python

Karpathy-Prinzip: deterministische Aufgaben an Software 1.0, semantische Aufgaben an das Modell.

| Aufgabe | Ausführer |
|---|---|
| Session-Logs finden und filtern | `reflect.py --mode list-unprocessed` |
| Lektionen, Muster, Fakten, Regeln, Fragen aus den Logs erkennen | Claude (LLM) |
| Vorschläge als strukturierte JSON-Liste formulieren | Claude (LLM) |
| Vorschläge atomar an Staging-Datei anhängen | `reflect.py --mode append-proposals` |
| `processed: true` in den verarbeiteten Logs setzen | `reflect.py --mode mark-processed` |

## Wann einsetzen

- Wenn mindestens ein Session-Log mit `status: complete` und `processed: false` existiert.
- Auf Zuruf ("Reflector durchlaufen lassen", "Session-Logs destillieren").
- Nach dem Weekly Review als zusätzliche Schicht der Reflexion.

## Ablauf (Ein-Durchlauf)

1. **Unverarbeitete Logs listen:**
   ```bash
   PYTHONUTF8=1 python .skills/reflector/reflect.py --mode list-unprocessed
   ```
   Gibt ein JSON-Objekt auf stdout aus mit Feldern `count`, `paths`, `staging_path`.

2. **Logs lesen und destillieren.** Claude liest jede gelistete Datei mit dem `Read`-Tool und extrahiert pro Datei folgende Kategorien, jeweils wenn sinnvoll:
   - **Lektion** — was wurde dazugelernt
   - **Fakt** — harte, zitierbare Aussage
   - **Regel** — explizite Arbeitsregel, die sich wiederholen soll
   - **Muster** — wiederkehrendes Verhalten oder Problemform
   - **Frage** — offene Frage, die der Nutzer beantworten muss

3. **Vorschlagsliste bauen.** Claude erzeugt ein JSON-Array nach diesem Schema:
   ```json
   [
     {
       "type": "lektion",
       "source": "session-2026-04-10-1432-thema.md",
       "content": "Beim Subprocess-Aufruf auf Windows muss PYTHONUTF8=1 gesetzt werden.",
       "target": "04 Ressourcen/Softwareentwicklung/Python unter Windows.md",
       "reason": "Bereits die zweite Session mit genau diesem Stolperstein."
     }
   ]
   ```
   Erlaubte `type`-Werte: `lektion`, `fakt`, `regel`, `muster`, `frage`.

4. **Vorschläge an Staging anhängen:**
   ```bash
   PYTHONUTF8=1 python .skills/reflector/reflect.py --mode append-proposals < proposals.json
   ```
   Das Skript validiert die Pflichtfelder, dedupliziert gegen bereits vorhandene Einträge, weist jedem Vorschlag eine laufende Nummer zu und setzt `status: proposed`. Es schreibt einen zeitgestempelten Block an die Staging-Datei an.

5. **Session-Logs als verarbeitet markieren:**
   ```bash
   PYTHONUTF8=1 python .skills/reflector/reflect.py --mode mark-processed --logs "<path1>" "<path2>"
   ```
   Setzt `processed: true` im Frontmatter der angegebenen Dateien. Nur Dateien unter `{logbuch}/Z Session Logs/` werden akzeptiert.

6. **Ergebnis melden.** Drei Sätze: wie viele Logs gelesen, wie viele Vorschläge ins Staging gewandert, was der bemerkenswerteste Fund war.

## Regeln

- **Niemals in Wiki-Dateien schreiben.** Der Skill darf nur `reflector-staging.md` und die gelesenen Session-Logs anfassen. Jeder Versuch, eine andere Datei zu schreiben, ist ein Bug.
- **Niemals halluzinieren.** Wenn ein Feld nicht aus dem Log ableitbar ist, bleibt es leer oder wird als Frage formuliert.
- **Maximal 500 Zeichen pro Vorschlags-`content`.** Länger bedeutet, der Vorschlag ist zu weich.
- **Bei Unsicherheit:** `type: frage`, `target: "unklar, Curator entscheidet"`.
- **Dedup-Regel:** Wenn ein vorgeschlagener `content` zu 80 Prozent (konfigurierbar via `dedup_threshold`) mit einem bestehenden `proposed`- oder `accepted`-Eintrag übereinstimmt, wird der neue Vorschlag verworfen.
- **Glossar nicht prüfen.** Das ist Curator-Aufgabe.
- **LLM-Psychologie-Check:** Der Reflector schlägt vor, urteilt nicht. Formulierungen wie "der Nutzer muss jetzt X" sind verboten. Stattdessen: "Muster erkannt: X wiederholt sich in mehreren Sessions."

## Pfade (Bundle-Platzhalter)

Die Pfade werden über den config_loader aus `bundle.json` aufgelöst:

- Session-Logs-Verzeichnis: `{logbuch}/Z Session Logs/`
- Staging-Datei: `{system}/Lerner Loop/reflector-staging.md`

Beide Pfade sind über `skill.config.yaml` überschreibbar (Schlüssel `session_logs_dir` und `staging_file` unter `paths:`).

## Eval-Set

Eingefrorene Assertions unter `.skills/reflector/eval/reflector.eval.json`. Der Runner ist `run_evals.py` im Skill-Ordner, arbeitet mit Fixtures in einem Temp-Verzeichnis. Pass-Rate muss 100 Prozent sein.

## Feature-Flags

Konfigurierbar in `skill.config.yaml` unter `features:`:

| Flag | Typ | Default | Beschreibung |
|---|---|---|---|
| `allow_create_staging` | bool | `true` | Staging-Datei anlegen, wenn sie noch nicht existiert |

Erweiterte Konfigurations-Optionen (keine reinen Booleans, weil Schwellwerte):

| Schlüssel | Typ | Default | Beschreibung |
|---|---|---|---|
| `dedup_threshold` | float | `0.8` | Mindest-Ähnlichkeit (0–1) für Deduplizierung |
| `max_content_length` | int | `500` | Maximale Zeichenzahl pro Vorschlags-`content` |

## Verknüpfungen

- [[INDEX|INDEX.md]]
- [[AGENTS|AGENTS.md]]
