Damit dein Claude nicht dümmer wird.

---
name: session-handoff
description: Schreibt ein detailliertes Handoff-Dokument am Ende einer Session, damit die nächste Session nahtlos weiterarbeiten kann. Benutze diesen Skill IMMER, wenn der User um eine Session-Dokumentation, Übergabe, Zusammenfassung-für-die-nächste-Session oder Context-Preservation bittet. Triggers in beliebiger Sprache (Deutsch oder Englisch) — z.B. "schreib handoff", "session handoff", "dokumentier session", "fasse session zusammen", "context für nächste session", "handoff schreiben", "session zusammenfassen", "summarize session for next session", "write handoff", "document the session", "create context for next time". Funktioniert für ALLE Session-Typen — bug-fix, feature-build, setup, planning, debug, research, workshop, refactor. Wählt adaptiv die richtigen Sektionen je nach Session-Typ aus, statt jede Sektion zu erzwingen. Output ist eine Markdown-Datei im project memory directory, plus ein Eintrag im MEMORY.md-Index, sodass die nächste Session den Handoff automatisch findet. Verwende diesen Skill, sobald der User auch nur ANDEUTET dass die jetzige Session für eine spätere fortsetzbar dokumentiert werden soll, nicht nur wenn "handoff" wörtlich erwähnt wird.
---

# Session-Handoff Skill

Schreibt am Ende einer Session ein strukturiertes Handoff-Dokument, das die nächste Session als "frozen state for resumption" nutzen kann.

## Kernprinzip

Ein Handoff ist **keine Zusammenfassung**. Es ist ein Übergabe-Dokument, das die folgende Frage beantworten muss:

> Könnte die nächste Session genau dort weiterarbeiten, wo wir aufgehört haben — mit null Erinnerung an unser Gespräch, nur mit diesem Dokument?

Wenn die Antwort ja ist → der Handoff ist gut. Wenn nein → fehlt Detail.

**Volume ist Feature, nicht Bug.** Lieber zu detailliert als zu knapp. 600+ Zeilen sind angemessen für eine substantielle Session. Aber: das Detail muss *strukturiert* sein. Ein TL;DR oben, danach scannable Sections.

## Workflow

### Schritt 1: Session-Typ identifizieren

Schau dir die Session an und wähle den dominanten Typ:

| Typ | Indikatoren | Spezifische Sektionen die du zusätzlich brauchst |
|-----|-------------|-------------------------------------------------|
| **bug-fix** | Probleme reproduziert, Root-Cause gefunden, Fix gebaut, getestet | Root-Cause-Analyse, Test-Vorher/Nachher |
| **feature-build** | Neue Komponenten/Endpoints/Logic geschrieben, Migration angelegt | Architektur-Entscheidungen + Reasoning, neue Dateien-Liste, Test-Evidence |
| **setup / config** | Tools installiert, Accounts angelegt, Env-Vars gesetzt, Auth eingerichtet | Credentials (Pfad, NICHT Werte!), Config-Files, Verifikations-Schritte |
| **planning** | Optionen diskutiert, Architektur skizziert, Entscheidung getroffen, kein Code geschrieben | Optionen erwogen mit Pros/Cons, Final-Decision + Reasoning, Next-Steps |
| **debug** | Bug noch nicht gefixt, aber tief untersucht, Hypothesen abgearbeitet | Hypothesen-Verlauf, was bisher ausgeschlossen, was Root-Cause ist (oder verbleibende Theorien) |
| **research** | Web-Search, Doku gelesen, externe APIs erkundet | Quellen + Links, Key-Findings, offene Fragen, was Sebastian noch validieren muss |
| **workshop / kunde** | Customer-Gespräch, Discovery, Anforderungen | Personen + Rollen, Action-Items mit Owner + Deadline, Follow-Up-Termine |
| **refactor** | Code umgebaut ohne Verhaltens-Änderung | Was umgebaut, Warum, Migration-Path, was bei nächster Iteration anders sein wird |

Falls die Session mehrere Typen kombiniert (z.B. bug-fix + feature): nimm alle relevanten Sektionen, stell sie chronologisch oder thematisch.

### Schritt 2: Memory-Pfad finden

Der Memory-Pfad ist projekt-spezifisch und steht im SessionStart-Hook-Output am Anfang jeder Session. Suche nach:

```
/Users/{user}/.claude/projects/{project-slug}/memory/
```

Falls dort nicht vorhanden: nutze stattdessen `.planning/handoffs/` im Projekt-Repo, oder frag den User.

### Schritt 3: Filename-Convention

```
SESSION-YYYY-MM-DD-{TOPIC-IN-CAPS}.md
```

- `YYYY-MM-DD`: Datum der Session (heute)
- `TOPIC-IN-CAPS`: Hauptthema in 2-4 Wörtern, hyphenisiert

**Beispiele:**
- `SESSION-2026-04-27-AUTH-REFACTOR-COMPLETE.md`
- `SESSION-2026-04-25-KICKOFF-MEETING-PREP.md`
- `SESSION-2026-04-20-API-V2-DEPLOY.md`
- `SESSION-2026-04-18-DB-MIGRATION-CLEANUP.md`

Falls die Session sehr substantiell ist und es schon einen früheren Handoff zum gleichen Thema gibt, suffix mit V2 / COMPLETE / FINAL — z.B. `SESSION-2026-04-27-AUTH-REFACTOR-COMPLETE.md` statt einfach `SESSION-2026-04-27-AUTH-REFACTOR.md`.

### Schritt 4: Frontmatter

Jede Handoff-Datei beginnt mit YAML-Frontmatter:

```markdown
---
name: Session YYYY-MM-DD {Topic} — {Subtitle, was war Schwerpunkt}
description: {1 Satz} {Was wurde gemacht} + {wichtigster Output} + {Status — committed/deployed/pending}.
type: project
originSessionId: {kurze-slug-id}
---
```

Beispiel-description: "Komplette Auth-Refactor-Session: 5 Bugs gefixt + 4 Features gebaut (Bulk-Upload, JWT-Refresh, Rate-Limit, Audit-Log). Alle E2E getestet, NICHTS committed/deployed. Quickstart-Section zeigt nächste Schritte."

Die description wird beim Skim der MEMORY.md gelesen — sie muss instant klar machen ob dieser Handoff für die aktuelle Frage relevant ist.

### Schritt 5: Universelle Sektionen schreiben (immer)

Diese Sektionen kommen **immer** vor, egal welcher Session-Typ:

#### TL;DR

3-5 Bullet Points oder ein kurzer Absatz. Was ist die wichtigste Aussage des ganzen Dokuments? Wenn die nächste Session NUR den TL;DR liest, was muss sie wissen?

Schlechte TL;DR: "Wir haben heute viel an X gearbeitet."
Gute TL;DR: "5 Bugs gefixt + 4 Features gebaut, alle getestet (9/9 grün), NICHTS committed/deployed. Staging-DB hat Test-Daten (Cleanup-SQL in Section 6)."

#### Was wurde gemacht

Strukturiert nach Topic oder Chronologie. Pro Item:
- Was war das Problem / die Anforderung?
- Was wurde gebaut/gefixt?
- Welche Datei wurde geändert?
- Wie wurde getestet?

**Code-Pfade als absolute Pfade.** `src/lib/services/pipeline.ts` ist mehrdeutig (welches Projekt?), `my-app/src/lib/services/pipeline.ts` ist klar.

#### Pending / Offen

Was ist noch nicht fertig? Ordne nach Priorität:
- Was MUSS die nächste Session tun (sonst ist die jetzige Session value-zerstörend)
- Was SOLLTE sie tun (Feature-Komplettierung)
- Was wäre NICE (Tech-Debt, Optimierungen)

Wenn nichts pending ist (rare): explicit schreiben "Nichts pending. Session ist abgeschlossen."

#### Quickstart für die nächste Session

Konkrete Befehle, die die nächste Session als ersten Output kopieren kann. Beispiel:

```bash
cd ~/Documents/Projects/my-app
git status --short
npx tsc --noEmit  # sollte clean sein
npm run dev       # falls UI-Tests nötig
```

Plus: Welche Datei zuerst lesen? Welche Test-Daten verwenden? Welches Login?

### Schritt 6: Bedingte Sektionen schreiben (je nach Session-Typ)

#### Bei bug-fix oder debug

**Root-Cause-Analyse:**
- Was war das beobachtete Symptom (was Sebastian gesehen hat)
- Was war die echte Ursache (technisch)
- Welche Hypothesen wurden ausgeschlossen?
- Wie wurde die Ursache validiert?

**Test-Evidence (Vorher/Nachher):**
| Test | Vorher | Nachher |
|------|--------|---------|
| Login-Endpoint Response | 500 Error ✗ | 200 OK ✓ |
| Token-Refresh match | flaky 60% | stable 100% ✓ |

#### Bei feature-build

**Architektur-Entscheidungen + Reasoning:**
Pro Entscheidung: was wurde gewählt? Was war die Alternative? Warum diese Wahl?

Beispiel: "Separate `documents`-Tabelle statt `products.document_sha256`-Spalte — weil bei Multi-Variant-Produkten die sha-Spalte sonst überschrieben wird → Dedup-Garantie kaputt."

**Neue Dateien-Liste:**
```
NEW src/lib/services/document-process.ts          Shared pipeline (sha256→extract→cache)
NEW src/components/document-bulk-upload.tsx        Multi-drop UI
M   src/app/api/invoices/[id]/route.ts             + 4 date fields in PUT
```

#### Bei setup / config

**Credentials + Pfade** (NIEMALS Plain-Text-Werte ins Handoff schreiben — nur Pfade wo sie liegen):
- "Login: `~/Documents/Projects/x/.env.local` — Variable `FOO_API_KEY`"
- "1Password Vault `Project-X`, Item `Azure Tenant`"
- NICHT: "Password ist hunter2"

**Config-Files mit Diff:**
Welche Konfigs wurden geändert. Welche neuen Werte. Welche Default überschrieben.

**Verifikations-Schritte:**
Wie kann die nächste Session prüfen dass das Setup noch funktioniert?
```bash
gcloud auth application-default print-access-token | head -c 20
# sollte einen Token-Prefix zurückgeben
```

#### Bei planning

**Optionen erwogen:**
| Option | Pros | Cons | Aufwand |
|--------|------|------|---------|
| Azure OpenAI Direct | DPA inkl. | Tenant-Kosten | 1 Tag Setup |
| Self-hosted Tenant | volle Kontrolle | mehr Aufwand | 3 Tage Setup |

**Final Decision + Reasoning:**
Nicht nur "wir nehmen Azure", sondern WARUM. Was war der Trigger? Welche Constraint hat die Wahl erzwungen?

**Next-Steps:**
Wer macht was bis wann?

#### Bei research

**Quellen mit Links:**
- arXiv-Paper: 2509.04469 (Paper-Title)
- Benchmark: benchmark-source.com/...
- Library-Doku: ...

**Key-Findings:**
3-5 Bullet Points, jeder mit Source-Verweis: "Model A besser als Model B/C für strukturierte Extraktion (Benchmark XY, +3-4 % Accuracy auf Detail-Items)"

**Offene Fragen:**
Was hat die Research nicht beantwortet? Was muss Sebastian/User-Side noch validieren?

#### Bei workshop / kunde

**Personen + Rollen:**
- Customer Lead (Firma, Rolle) — Entscheider
- Operative Ansprechperson (Team) — Tages-Kontakt

**Action-Items mit Owner + Deadline:**
| Item | Owner | Deadline |
|------|-------|----------|
| AGB schicken | Kunde | 30.04. |
| OAuth einrichten | Du | 02.05. |

**Follow-Up-Termine:**
Datum, Uhrzeit, Plattform, was besprochen werden soll.

### Schritt 7: Universelle Optional-Sektionen (wenn relevant)

Diese sind nicht type-spezifisch, sondern context-spezifisch. Inkludiere sie, wenn anwendbar:

- **Repo-Zustand am Session-Ende** — `git status --short` Output, letzter Commit-Hash, Branch
- **Migrations** — wenn DB-Änderungen, SQL für Rollback-Reference
- **Kosten-Summary** — wenn externe APIs verwendet (Bedrock, Gemini, OpenAI, Apify)
- **Gefahren / Foot-Guns** — was bei der Weiterarbeit explodieren könnte (z.B. "resetItems: true LÖSCHT alle ChildItems — preservedRefs-Logik MUSS funktionieren")
- **Wichtige IDs** — Test-Invoices, User-IDs, Project-IDs
- **Architektur-Diagramm (mental model)** — ASCII-Box-Diagramm wenn das System komplex genug ist
- **Was Sebastian noch im UI testen sollte** — wenn UI-Tests nicht durchgeführt wurden

### Schritt 8: MEMORY.md Index updaten

Nach dem Schreiben der Handoff-Datei → Index updaten, sodass die nächste Session den Handoff findet.

Suche `MEMORY.md` im selben Verzeichnis wie die Handoff-Datei. Wenn nicht vorhanden: erstelle nicht — der User hat dann andere Konventionen.

Insertion-Point: am Anfang der Datei, im "AKTIV"-Bereich. Format folgt dem existing-Pattern:

```markdown
## 🎯 AKTIV: {Topic} ({Datum}) — NÄCHSTE SESSION ZUERST LESEN
- **[{Title}]({Filename}.md)** — {one-liner Zusammenfassung mit Status}
```

**Status-Marker je nach Session:**
- `🎯 AKTIV` — Session ist mid-flight, Pending-Items relevant für nächste Session
- `✅ DONE` — Session ist abgeschlossen, nichts mehr zu tun, nur Archiv
- `⚠️` — Warning / Issue / Bug bekannt, Vorsicht bei Weiterarbeit

Wenn der neue Handoff einen alten zu demselben Topic ersetzt: alten Eintrag in der MEMORY.md auf "überholt von" markieren, nicht löschen (Historie wertvoll).

### Schritt 9: Quality-Check vor dem Abgeben

Bevor du den Skill als fertig deklarierst, geh die Datei durch und prüfe:

- [ ] **TL;DR-Test**: Wenn jemand nur die ersten 10 Zeilen liest, weiß er was passiert ist?
- [ ] **Resumption-Test**: Könnte ich diese Session blind in 2 Wochen weitermachen, nur mit diesem Doc?
- [ ] **File-Path-Test**: Sind alle Code-Referenzen absolute Pfade ODER eindeutig relativ zum Repo-Root?
- [ ] **Status-Test**: Ist klar was committed/deployed/pending ist?
- [ ] **Quickstart-Test**: Hat die nächste Session konkrete Copy-Paste-Befehle für ihren Start?
- [ ] **Pending-Test**: Sind Pending-Items priorisiert (must vs should vs nice)?
- [ ] **Credential-Hygiene**: KEINE Plain-Text-Passwords/Tokens — nur Pfade wo sie liegen
- [ ] **Memory-Index**: MEMORY.md ist updated, neuer Eintrag ist sichtbar in den ersten 25 Zeilen

Wenn ein Check fehlschlägt → ergänzen, BEVOR du dem User berichtest "fertig".

### Schritt 10: Bericht an den User

Kurzer Output an den User mit:
1. **Pfad zur Handoff-Datei** (klickbar)
2. **Zeilenanzahl** (gibt Eindruck der Tiefe — 200 Zeilen = leicht, 600 Zeilen = substantiell)
3. **MEMORY.md Update bestätigt** (kurze Zeile)
4. **Was direkt im nächsten Kontext geladen wird** (welcher MEMORY-Eintrag)

Beispiel:
> ✓ Handoff geschrieben (663 Zeilen)
> Pfad: `~/.claude/projects/foo/memory/SESSION-2026-04-27-...md`
> MEMORY.md updated — neuer Eintrag steht ganz oben unter "🎯 AKTIV"
> Nächste Session lädt diesen Handoff automatisch beim Start

## Anti-Patterns — vermeide diese

**Wall-of-Text ohne TL;DR**
> "In dieser Session haben wir uns mit der Auth-Pipeline beschäftigt. Zuerst haben wir das Token-Refresh-Problem analysiert..."

→ Stattdessen: TL;DR oben, dann Detail.

**Generische Status-Phrasen**
> "Es funktioniert jetzt." / "Tests sind grün."

→ Stattdessen: konkrete Test-Outputs zitieren ("9/9 API-Asserts grün, siehe `bash scripts/test-e2e.sh`").

**Fehlende file paths**
> "Wir haben pipeline.ts geändert."

→ Stattdessen: `my-app/src/lib/services/pipeline.ts:790-820 — checkValidation bekommt jetzt extraParams-Parameter`.

**Action-Items ohne Owner**
> "AGBs müssen geschickt werden."

→ Stattdessen: "AGBs schicken — Owner: Kunde, Deadline: 30.04. — Status: warten auf Kunde".

**Credentials im Klartext**
> "Login: user@example.com / temp-pw-2026"

→ Niemals. Stattdessen: "Login dokumentiert in `memory/NEXT-SESSION-NOTES.md` Zeile 63" ODER nur im AUTO-MEMORY-File, das nicht synchronisiert wird.

**Vergessen was deployed ist**
> "Feature ist fertig."

→ Stattdessen: "Feature ist fertig + getestet, ABER: nichts committed, nichts deployed. Bei nächster Session: Sebastian sichten + entscheiden welche Files committed werden."

**Pending ohne Priorität**
> "Noch zu tun: A, B, C, D, E"

→ Stattdessen: "MUSS: A (sonst nicht-deployable). SOLLTE: B, C. NICE: D, E."

## Schreibstil

- **Imperative + 2nd-person für Quickstart** ("Tippe `gcloud auth login`")
- **Past tense für was-gemacht-wurde** ("Migration durch, sha256-Spalte angelegt")
- **Tabellen für Vergleiche/Listen** statt Bullet-Points wenn 3+ Spalten
- **Code-Blocks** für Commands, SQL, JSON
- **Bold für critical phrases** ("**NICHTS COMMITTED**" — fett, weil das einer der wichtigsten Status-Markers ist)
- **Emojis als Status-Marker** (✓ done, ⚠️ warning, 🎯 active, → next-step) — sparsam einsetzen, nicht dekorativ

## Length-Guidance

| Session-Substanz | Erwartete Zeilen |
|------------------|------------------|
| Quick fix (15 min) | 50-100 |
| Substantielle bug-fix oder Feature (1-3h) | 200-400 |
| Major Session (4h+, multiple Tasks) | 400-800 |
| Mega-Session (full day, viele Bereiche) | 800-1500 |

Falls dein Handoff weit über diesen Bereichen liegt: prüfen ob du redundant bist. Falls weit darunter: prüfen ob du Detail vergessen hast.

## Beispiele für Handoff-Typen als Referenz

Diese Filename-Patterns helfen, wenn du gerade einen schreibst:

- `SESSION-2026-04-27-AUTH-REFACTOR-COMPLETE.md` (663 Zeilen) — Major-Session, multi-feature, mit allen optionalen Sektionen
- `SESSION-YYYY-MM-DD-BUGFIX-AUTH.md` — Bug-Fix-fokus, mit Root-Cause + Test-Evidence
- `SESSION-2026-04-21-22-TRADING-BACKTEST-MASTER-HANDOFF.md` — Research-Heavy, mit Quellen + Findings
- `SESSION-YYYY-MM-DD-KICKOFF-PREP.md` — Customer/Workshop-Prep mit Action-Items

Bei Unsicherheit: schau dir zwei davon an, vergleiche Strukturen, übernimm die passende für deinen Fall.