# Otterly.ai Prompt Transformation Guide

**Last Updated:** 2025-12-10

## Overview

The Otterly.ai prompt generation system automatically transforms keywords and search queries into conversational AI prompts (10-25 words, full sentences, question format). This ensures prompts match how users actually query AI assistants like ChatGPT, Perplexity, and Google AI Overviews.

## Why Conversational Prompts?

**Traditional SEO Keywords** (not suitable for AI search):

- "schichtplanung"
- "zeiterfassung"
- "Ordio vs Planday"

**Conversational AI Prompts** (suitable for AI search):

- "Welche Software eignet sich am besten für die Schichtplanung in der Gastronomie?"
- "Wie unterscheidet sich Ordio von Planday für die Schichtplanung?"

**Key Differences:**

- **Length**: 10-25 words vs 1-5 words
- **Format**: Full sentences vs keyword lists
- **Structure**: Question format vs statements
- **Context**: Industry/use case included vs minimal context

## Transformation System

### Components

1. **Prompt Templates** (`v2/data/otterly/prompt-templates.json`)

   - Template library for each intent type
   - 3-5 templates per intent for variety
   - Placeholders: `{keyword}`, `{industry}`, `{use_case}`, `{company_size}`

2. **Context Rules** (`v2/data/otterly/context-rules.json`)

   - Industry indicators (gastronomie, einzelhandel, pflege, handwerk)
   - Use case indicators (schichtplanung, zeiterfassung, personalverwaltung)
   - Company size indicators (small, medium, large)
   - Context phrases for natural German

3. **Transformation Functions** (`v2/scripts/otterly/generate-otterly-prompts.php`)
   - `analyzeQuery()` - Extracts intent, keywords, industry, use case
   - `transformKeywordToPrompt()` - Converts keywords to conversational prompts
   - `transformGSCQueryToPrompt()` - Converts GSC queries to conversational prompts
   - `transformCompetitorPrompt()` - Converts competitor names to conversational comparisons
   - `transformIndustryPrompt()` - Creates industry-specific conversational prompts

### Transformation Process

1. **Analyze Input**: Extract intent, keywords, industry, use case from query/keyword
2. **Select Template**: Choose appropriate template based on intent
3. **Fill Placeholders**: Replace `{keyword}`, `{industry}`, `{use_case}` with actual values
4. **Add Context**: Include industry/use case context phrases
5. **Clean Up**: Fix grammar, remove duplicate words, ensure proper punctuation
6. **Validate**: Check length (10-25 words), question format, natural structure

## Template Reference

### Informational Intent

**Templates:**

- "Was ist {keyword} und wie funktioniert es?"
- "Welche Bedeutung hat {keyword} in {industry}?"
- "Wie funktioniert {keyword} in der Praxis?"

**Example:**

- Input: "schichtplanung", intent: "informational", context: ["industry" => "gastronomie"]
- Output: "Welche Bedeutung hat die Schichtplanung in der Gastronomie?"

### Solution-Seeking Intent

**Templates:**

- "Welche Software eignet sich am besten für {keyword} in {industry}?"
- "Welche Lösung eignet sich für {use_case} in {industry}?"
- "Welche Tools gibt es für {keyword} in {industry} und wie funktionieren sie?"

**Example:**

- Input: "zeiterfassung", intent: "solution_seeking", context: ["industry" => "gastronomie"]
- Output: "Welche Software eignet sich am besten für die Zeiterfassung in der Gastronomie?"

### Comparative Intent

**Templates:**

- "Wie unterscheidet sich {product1} von {product2} für {use_case}?"
- "Welche Alternativen gibt es zu {competitor} für {use_case}?"
- "Was sind die Vor- und Nachteile von {product1} gegenüber {product2}?"

**Example:**

- Input: "Planday", type: "direct_comparison"
- Output: "Wie unterscheidet sich Ordio von Planday für die Schichtplanung?"

### Task-Based Intent

**Templates:**

- "Wie kann ich {keyword} in {industry} umsetzen?"
- "Wie digitalisiere ich {keyword} für {use_case}?"
- "Schritt für Schritt: {keyword} in {industry} einführen"

**Example:**

- Input: "schichtplanung", intent: "task_based", context: ["industry" => "gastronomie"]
- Output: "Wie kann ich die Schichtplanung in der Gastronomie umsetzen?"

## Context Extraction

### Industry Detection

The system automatically detects industry from queries:

- **Gastronomie**: restaurant, café, bar, gastronomie, küche
- **Einzelhandel**: laden, shop, retail, einzelhandel
- **Pflege**: krankenhaus, pflege, klinik, gesundheitswesen
- **Handwerk**: baustelle, werkstatt, handwerk, handwerker

**Example:**

- Query: "zeiterfassung gastronomie"
- Detected: industry = "gastronomie"
- Context phrase: "in der Gastronomie"

### Use Case Detection

The system detects use cases from queries:

- **Schichtplanung**: dienstplan, schichtplan, personalplanung
- **Zeiterfassung**: arbeitszeit, stempeluhr, zeiterfassung
- **Personalverwaltung**: personalakte, mitarbeiter, hr
- **Lohnabrechnung**: lohn, gehalt, payroll, lohnabrechnung

**Example:**

- Query: "dienstplan tvöd"
- Detected: use_case = "schichtplanung"
- Context phrase: "für die Schichtplanung"

## Quality Scoring

### Conversational Quality Score (0-50 points)

- **Length (10-25 words)**: +20 points
- **Question format**: +15 points
- **Natural language structure**: +10 points
- **Context inclusion**: +15 points
- **Keyword stuffing penalty**: -5 points

### Integration with Main Scoring

Conversational quality score is added to the main prompt score (20-30% weight), ensuring conversational prompts rank higher than keyword-only prompts.

## Validation

### Conversational Prompt Check

A prompt is considered conversational if it meets ALL criteria:

1. **Minimum 8 words**
2. **Contains question words** (was, wie, welche, wann, etc.) OR task verbs (erstellen, digitalisieren, etc.)
3. **Natural sentence structure** (starts with capital, ends with punctuation)
4. **Has structure words** (für, in, mit, von, etc.) - not just keyword list

### Filtering

Non-conversational prompts are filtered out unless they have:

- High impressions (> 500) from GSC
- High clicks (> 10) from GSC
- Conversion data from GA4

## Examples

### Keyword Transformation

**Before**: `schichtplanung`
**After**: `Welche Software eignet sich am besten für die Schichtplanung in der Gastronomie?`
**Words**: 1 → 12 words
**Improvements**: Added question format, industry context, natural phrasing

### GSC Query Transformation

**Before**: `zeiterfassung gastronomie`
**After**: `Welche Software eignet sich für Zeiterfassung in der Gastronomie?`
**Words**: 2 → 10 words
**Improvements**: Converted keyword pair to full question with proper structure

### Competitor Transformation

**Before**: `Ordio vs Planday`
**After**: `Wie unterscheidet sich Ordio von Planday für die Schichtplanung?`
**Words**: 3 → 10 words
**Improvements**: Added context (use case), natural comparison phrasing

## Best Practices

1. **Always use transformation functions** - Don't create prompts manually
2. **Provide context when available** - Industry, use case, company size
3. **Select appropriate intent** - Match intent to template type
4. **Validate output** - Check word count, question format, naturalness
5. **Review grammar** - Fix any "Welche die" or "für in" patterns

## Troubleshooting

### Issue: Prompts too short (< 10 words)

**Solution**:

- Use longer templates (15-20 words)
- Add more context (industry, use case)
- Use templates with explanatory phrases

### Issue: Grammatical errors ("Welche die", "für in")

**Solution**:

- Check placeholder replacement logic
- Fix article usage in `transformKeywordToPrompt()`
- Improve cleanup regex patterns

### Issue: Missing context

**Solution**:

- Improve `analyzeQuery()` industry/use case detection
- Add more keywords to context-rules.json
- Manually provide context in transformation call

### Issue: Incomplete phrases

**Solution**:

- Fix placeholder removal logic
- Improve cleanup regex to handle "in?" patterns
- Ensure all placeholders are replaced before cleanup

## Files Reference

- **Templates**: `v2/data/otterly/prompt-templates.json`
- **Context Rules**: `v2/data/otterly/context-rules.json`
- **Generator**: `v2/scripts/otterly/generate-otterly-prompts.php`
- **Test Script**: `v2/scripts/otterly/test-prompt-quality.php`
- **Validation**: `v2/scripts/otterly/validate-prompts.php`

## See Also

- `docs/ai/otterly-prompt-research-process.md` - Complete process documentation
- `docs/otterly-prompt-research.md` - Research and methodology
- `docs/ai/otterly-prompt-transformation-comparison.md` - Before/after comparison