> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crisisiq.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt-Architektur

> Detaillierte Analyse des Prompt-Systems im Scenario Creator Backend

## Übersicht

Das Prompt-System ist das Herzstück des Scenario Creator Backends. Es besteht aus 10 Dateien mit insgesamt \~2.185 Zeilen Code, die verschiedene Aspekte der Szenario-Generierung steuern.

## Research-Erkenntnisse (Version 2.0)

### Lange Prompts sind korrekt

Initiale Annahme, dass System Prompts kurz sein sollten, war **falsch**. Research zeigt:

| Quelle                             | Erkenntnis                                                                                                                                                         |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Claude 4 System Prompt Analyse** | Claudes eigener System Prompt hat mehrere Hauptsektionen: Identity, Boundaries, Tone, Safety, Tool Instructions. Verwendet XML-Tags, ALL CAPS für kritische Regeln |
| **OpenAI GPT-4.1 Guide**           | Empfiehlt: Role → Instructions → Sub-categories → Reasoning Steps → Output Format → Examples → Context → Final instructions                                        |
| **Enterprise Prompt Engineering**  | "Prompts können viele Absätze lang sein... Prompts wie produktisierte Schnittstellen behandeln: designed, versioniert, getestet"                                   |

**Schlussfolgerung**: Lange, detaillierte System Prompts sind angemessen. Das Problem ist **Organisation**, nicht Länge.

### Strukturelle Prinzipien

| Prinzip                        | Quelle                  | Anwendung                                                   |
| ------------------------------ | ----------------------- | ----------------------------------------------------------- |
| **Sandwich-Methode**           | OpenAI GPT-4.1          | Kritische Instruktionen sowohl am START als auch am ENDE    |
| **XML-Tags für Struktur**      | Anthropic Docs          | `<instructions>`, `<rules>`, `<examples>`                   |
| **Positiv statt negativ**      | Claude 4 Best Practices | "Sage was zu tun IST, nicht was NICHT zu tun ist"           |
| **WHY erklären**               | Claude 4 Best Practices | "Reasoning-Kontext liefern statt nur Regeln zu nennen"      |
| **Kein aggressives Prompting** | Claude 4 Best Practices | Nicht "KRITISCH: Du MUSST" - Claude 4 ist bereits responsiv |
| **ALL CAPS für Kritisches**    | Claudes eigener Prompt  | Betonung nur für nicht-verhandelbare Regeln                 |
| **Context first, Query last**  | Anthropic Long Context  | Dokumente oben, Instruktionen unten                         |
| **Prefill für JSON**           | Anthropic Prefill Guide | Assistant Response mit `{` starten                          |

### Was aktuelle Prompts falsch machen

| Problem            | Aktueller Ansatz                           | Research sagt                            |
| ------------------ | ------------------------------------------ | ---------------------------------------- |
| Regel-Framing      | Stark negativ ("VERBOTEN", "NIEMALS", "⛔") | Positives Framing funktioniert besser    |
| Regel-Hierarchie   | Alle Regeln flach präsentiert              | Explizite MUST/SHOULD/MAY Stufen         |
| Kritische Betonung | Alles ist "KRITISCH"                       | Nur wirklich kritische Items in ALL CAPS |
| Struktur           | Verstreute Sektionen                       | Hierarchisch mit XML-Tags                |
| Beispiele          | Inline mit Regeln                          | Dedizierte `<examples>` Sektion          |
| Sandwich           | Instruktionen nur am Start                 | Kritische Regeln am Ende wiederholen     |

## Prompt-Dateien Inventar

| Datei                       | Zeilen | Zweck               | Status |
| --------------------------- | ------ | ------------------- | ------ |
| `tocPrompt.js`              | 465    | TOC-Generierung     | Aktiv  |
| `validatePrompt.js`         | 231    | Validierung         | Aktiv  |
| `modelSelectorPrompt.js`    | 86     | Modell-Auswahl      | Aktiv  |
| `event/systemPrompt.js`     | 397    | Event System Prompt | Aktiv  |
| `event/generatePrompt.js`   | 310    | Event User Prompt   | Aktiv  |
| `event/regeneratePrompt.js` | 44     | Regenerierung       | Aktiv  |
| `event/microEditPrompt.js`  | 118    | Mikro-Bearbeitung   | Aktiv  |
| `event/validationPrompt.js` | 191    | Validierungs-Fix    | Aktiv  |
| `event/helpers.js`          | 331    | Hilfsfunktionen     | Aktiv  |
| `event/index.js`            | 12     | Barrel Export       | Aktiv  |

## Detaillierte Prompt-Analyse

### 1. TOC Prompt (`tocPrompt.js`)

**Zweck**: Generiert die komplette Story-Struktur als Graph-Modell.

#### Stärken

* Umfassende Regeln für Graphen-Modell
* Klare Beispiele für Event-Struktur
* Explizite Zeitkonsistenz-Regeln

#### Herausforderungen

Das TOC-Prompt hat \~370 Zeilen mit 12+ Regel-Sektionen:

1. **JSON-Struktur-Anforderungen**
2. **Zeitregeln** (6 verschiedene zeitsynchrone Sektionen)
3. **Verzweigungslogik**
4. **Assessment-Platzierung**
5. **NPC-Verwaltung**
6. **Konvergenz-Handling**

#### Kritische Zeitregeln

```
ZEITREGEL (Aktuell):
- Jedes Event muss zeitlich nach seinen Vorgängern liegen
- Parallele Pfade müssen synchronisiert werden
- Konvergenzpunkte müssen alle Vorgänger berücksichtigen
- Tag/Uhrzeit Format: "Tag X, HH:MM Uhr"
- Zeitsprünge müssen narrativ begründet sein
- Keine Zeitschleifen
```

**Problem**: Diese Regeln sind über 6 Sektionen verteilt, was zu kognitiver Überlastung führt.

### 2. Event System Prompt (`event/systemPrompt.js`)

**Zweck**: Definiert den literarischen Stil und die Qualitätsanforderungen für Event-Texte.

#### Struktur

* **\~400 Zeilen** mit 15+ Sektionen
* Literarischer Stil-Guide
* "Show don't tell" Prinzipien
* Zeichenanzahl-Vorgaben

#### Kern-Anforderungen

| Anforderung     | Spezifikation                | Typ   |
| --------------- | ---------------------------- | ----- |
| Zeichenanzahl   | 500-2.000 Zeichen (flexibel) | Weich |
| Sinneseindrücke | 2-3 pro Event                | Weich |
| Dramaturgie     | Spannungsbogen               | Weich |
| Perspektive     | 2. Person Singular           | Hart  |
| Sprache         | Deutsch (DE)                 | Hart  |

**Hinweis**: Komplexe Szenen mit viel Dialog oder mehreren NPCs benötigen mehr Platz. Einfache Übergangsszenen können kürzer sein.

#### Stil-Richtlinien

```
SHOW DON'T TELL Beispiele:

❌ Schlecht: "Sie sind nervös."
✅ Gut: "Ihre Finger trommeln auf dem Tisch."

❌ Schlecht: "Der Raum ist chaotisch."
✅ Gut: "Akten stapeln sich auf dem Boden, leere Kaffeetassen säumen den Schreibtisch."
```

### 3. Event Generate Prompt (`event/generatePrompt.js`)

**Zweck**: Baut den konkreten User-Prompt für jedes Event auf.

#### Kontext-Injektion

Der Prompt injiziert folgende Kontexte:

1. **Formular-Daten**
   * Industrie
   * Szenario-Typ
   * Schwierigkeitsgrad
   * Titel & Beschreibung

2. **TOC-Struktur**
   * Vollständiger Graph
   * Alle Event-IDs
   * Verzweigungslogik

3. **NPC-Registry**
   * Bereits verwendete NPCs
   * Charakter-Beschreibungen

4. **Vorgänger-Inhalte**
   * Vollständiger Text aller direkten Vorgänger
   * Zeit-Constraints

5. **Konvergenz-Information**
   * Ob dieses Event ein Konvergenzpunkt ist
   * Welche Pfade zusammenlaufen

#### Typischer Prompt-Aufbau

```
Industrie: [X]
Szenario-Typ: [Y]
Schwierigkeitsgrad: [Z]

TOC-Struktur:
[Gesamter Graph als JSON]

Bereits verwendete NPCs:
[NPC-Liste]

Vorgänger-Event(s):
[Vollständiger Text]

Zeitbeschränkungen:
Muss nach: [Latest Predecessor Time]

GENERIERE JETZT: Event [event_id]
```

### 4. Validation Prompt (`validatePrompt.js`)

**Zweck**: Post-hoc Validierung des gesamten generierten Szenarios.

#### Validierungs-Kategorien

| Kategorie          | Severity | Beispiele                                   |
| ------------------ | -------- | ------------------------------------------- |
| **Zeitfehler**     | CRITICAL | Zeitsprünge rückwärts, inkonsistente Marker |
| **Strukturfehler** | CRITICAL | Fehlende Events, gebrochene Verzweigungen   |
| **Inhaltsfehler**  | HIGH     | NPC-Inkonsistenzen, Plot-Holes              |
| **Stilfehler**     | MEDIUM   | Zeichenanzahl, Sinneseindrücke              |
| **Kleinigkeiten**  | LOW      | Tippfehler, Formatierung                    |

#### Explizite "Was NICHT flaggen"

```
NICHT flaggen:
- Kreative Entscheidungen im Stil
- Dramaturgische Variationen
- Unterschiedliche NPC-Darstellungen (solange konsistent)
- Zeitsprünge die narrativ begründet sind
```

#### Problem

**Post-hoc Only**: Validierung läuft erst NACH Generierung aller Events. Fehler in Event 2 können sich durch Event 3, 4, 5... fortpflanzen, bevor sie erkannt werden.

### 5. Regeneration & Micro-Edit

#### Regenerate Prompt (`event/regeneratePrompt.js`)

* **44 Zeilen**: Kompakt und fokussiert
* Integriert User-Feedback
* Behält Kontext bei

#### Micro-Edit Prompt (`event/microEditPrompt.js`)

* **118 Zeilen**: Chirurgische Änderungen
* Für einzelne Probleme (z.B. Tippfehler, NPC-Namen)
* Verwendet Haiku-Modell (kostengünstig)

### 6. Model Selector Prompt (`modelSelectorPrompt.js`)

**Zweck**: Wählt das optimale Claude-Modell basierend auf Aufgaben-Komplexität.

#### Entscheidungskriterien (aktuell)

```
Haiku:
- Einfache Struktur-Validierung
- Micro-Edits
- Standardisierte Aufgaben

Sonnet:
- Standard-Szenario-Generierung
- Mittlere Komplexität
- TOC mit <20 Events

Opus:
- Sehr komplexe Szenarien
- >30 Events
- Multiple Verzweigungen
- Hohe Qualitätsanforderungen
```

#### Problem

**Vage Kriterien**: "sehr komplex" ist subjektiv und führt zu inkonsistenter Auswahl.

## Helper-Funktionen

### Zeit-Management (`event/helpers.js`)

#### Aktuelle Implementierung

```javascript theme={null}
// String-basierter Vergleich
pred.time_marker > latestPredecessor.time_marker
```

**Problem**: Funktioniert NICHT für Edge Cases:

* "Tag 1, 23:59" vs "Tag 2, 00:01"
* Verschiedene Formatierungen

#### Vorgänger-Suche

```javascript theme={null}
function findAllPredecessorIds(eventId, toc) {
  // Aktuell: Ein Level tief
  // Problem: Verpasst transitive Abhängigkeiten
}
```

**Konsequenz**: Bei langen Ketten können Zeitfehler auftreten.

## Prompt-Effizienz-Analyse

### Redundanz-Probleme

| Problem                      | Häufigkeit  | Impact             |
| ---------------------------- | ----------- | ------------------ |
| **Kontext-Duplizierung**     | Jeder Call  | \~30-40% Redundanz |
| **TOC wird wiederholt**      | Jedes Event | \~2-3K Tokens/Call |
| **FormData wird wiederholt** | Jedes Event | \~500 Tokens/Call  |

### Token-Verbrauch pro Aufgabe

```
TOC Generation:
Input: ~8.500 Tokens
Output: ~2.000 Tokens
Total: ~10.500 Tokens

Event Generation (3 Events):
Input: ~12.000 Tokens
Output: ~3.000 Tokens
Total: ~15.000 Tokens

Validation:
Input: ~15.000 Tokens (gesamtes Szenario)
Output: ~1.000 Tokens
Total: ~16.000 Tokens
```

### Sprach-Konsistenz

**Aktuelles Problem**: Gemischte EN/DE Labels

```javascript theme={null}
// In User Prompts:
"Title: [titel]"           // English label, German content
"Industry: [industrie]"    // English label, German content

// Erwartete Ausgabe: Deutsch
// Kann zu Sprach-Leakage führen
```

## Vorgeschlagene Prompt-Struktur

### System Prompt Template (6 Sektionen)

Basierend auf Research sollten System Prompts dieser Struktur folgen:

1. **IDENTITY & MISSION** (\~100-150 Wörter)
   * Wer du bist (Rolle, Expertise)
   * Was du produzierst
   * Kern-Constraints (Sprache, Perspektive)

2. **OUTPUT FORMAT**
   * JSON-Struktur-Skelett
   * Required Fields
   * Format FRÜH zeigen, damit Modell das Ziel kennt

3. **RULES (hierarchisch)**
   ```xml theme={null}
   <rules_must>
   UNVERHANDELBAR - Verletzung führt zu Ablehnung:
   - Valid JSON output
   - Unique event_ids
   - Time always forward
   </rules_must>

   <rules_should>
   QUALITÄTSSTANDARD - Verletzung mindert Qualität:
   - 500-2000 chars per event
   - 2-3 senses per event
   </rules_should>

   <rules_may>
   OPTIONAL - Verbessert das Ergebnis:
   - Specific NPC archetypes
   - Dramatic cliffhangers
   </rules_may>
   ```

4. **DETAILED GUIDANCE**
   * Domain-spezifische Instruktionen
   * Stil-Guide
   * Edge Cases
   * Organisiert mit XML-Tags: `<time_rules>`, `<style_guide>`, etc.

5. **EXAMPLES**
   ```xml theme={null}
   <examples>
   Ein komplettes, hochwertiges Beispiel des erwarteten Outputs
   </examples>
   ```

6. **FINAL REMINDER (Sandwich)**
   * MUST-Regeln in kondensierter Form wiederholen
   * JSON only
   * Time forward
   * All event\_ids unique

### User Prompt Template (3 Sektionen)

1. **CONTEXT DATA (oben - longform zuerst)**
   ```xml theme={null}
   <scenario_config>
   Full formData - ALLE Details für Konsistenz
   </scenario_config>

   <toc>
   Full TOC structure
   </toc>

   <previous_events>
   Previously generated events
   </previous_events>
   ```

2. **DERIVED CONTEXT (berechnete Helfer)**
   ```xml theme={null}
   <npc_registry>
   Welche NPCs wo eingeführt
   </npc_registry>

   <time_constraints>
   Latest predecessor times
   </time_constraints>
   ```

3. **SPECIFIC TASK (unten - Query zuletzt)**
   ```xml theme={null}
   <task>
   Clear instruction: was generieren, welche event_ids
   </task>

   <checklist>
   Quick self-check vor Output
   </checklist>
   ```

### Regel-Framing: Negativ → Positiv

| Aktuell (Negativ)                          | Vorgeschlagen (Positiv + WHY)                                                                                                              |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `⛔ VERBOTEN: NIEMALS englische Wörter`     | `Schreibe auf Deutsch. Verwende deutsche Fachbegriffe (z.B. "prüfen" statt "checken"), da die Zielgruppe deutschsprachige Fachleute sind.` |
| `⛔ KRITISCH: Unter 1.800 Zeichen = FEHLER` | `Ziel: 500-2000 Zeichen pro Event. Komplexe Szenen mit viel Dialog benötigen mehr Platz. Einfache Übergangsszenen können kürzer sein.`     |
| `NIEMALS rückwärts in der Zeit!`           | `Zeit fließt immer vorwärts. Jedes Event muss zeitlich nach seinem Vorgänger liegen, da die Geschichte chronologisch erlebt wird.`         |

### Konsolidierte Zeitregeln

**Aktuell**: 6 verstreute Sektionen über Zeit.

**Vorgeschlagen**: EINE dedizierte Sektion:

```xml theme={null}
<time_rules>
ZEITLOGIK

Eine einzige Regel: Zeit fließt vorwärts.

Für jedes Event gilt:
  time_marker MUSS später sein als ALLE Events, die zu diesem führen.

Bei Konvergenz (mehrere Pfade führen zu einem Event):
  Der Konvergenz-Event muss NACH dem spätesten aller Vorgänger liegen.

  Beispiel:
  - e4a endet um 10:15
  - e4b endet um 10:18
  - e4c endet um 10:20 ← spätester
  → e5 muss 10:21 oder später sein

Format: "Tag X, HH:MM Uhr"

Vor Abgabe prüfen:
  Folge jedem Pfad von e1 bis zum Ende.
  Ist die Zeit in jedem Schritt aufsteigend? ✓
</time_rules>
```

## Best Practices (abgeleitet)

### Was funktioniert gut

1. **Klare Beispiele**: "Show don't tell" Beispiele sind sehr effektiv
2. **Strukturierte Ausgabe**: JSON-Format mit Schema funktioniert zuverlässig
3. **Kontext-Injektion**: Vorgänger-Inhalte helfen bei Konsistenz
4. **Severity Levels**: Klare Priorisierung in Validierung

### Was verbessert werden sollte

1. **Prompt-Restrukturierung mit XML-Tags** (P0)
2. **Regel-Hierarchie hinzufügen**: MUST vs SHOULD vs MAY (P0)
3. **Positives Regel-Framing**: Negativ → Positiv konvertieren (P0)
4. **Zeitregeln konsolidieren**: Zu EINER Sektion zusammenfassen (P0)
5. **Sandwich-Methode**: MUST-Regeln am Ende wiederholen (P0)
6. **Zeit-Parsing**: Strukturierter Vergleich statt String (P1)
7. **Sprach-Konsistenz**: Alle Labels auf Deutsch (P1)
8. **TOC-Output optimieren**: Schlankere Struktur (P1)

## Nächste Schritte

Siehe [Bekannte Probleme & Verbesserungen](/internal/known-issues) für detaillierte Verbesserungsvorschläge.