# Nano AI Conversation Examples - Maintenance Guide

**Last Updated:** 2026-03-18

## Purpose

The conversation examples in `docs/data/nano-ai-conversation-examples.json` showcase Nano AI's capabilities on the Nano AI product page. They appear in the conversation-cards component as interactive demos that animate user/AI exchanges and highlight time savings.

## JSON Structure

### Root Object

- `generated_at` (optional): ISO 8601 timestamp
- `conversations` (required): Array of conversation objects
- `categories` (required): Array of category metadata

### Conversation Object

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique identifier (e.g. `shift-replacement-workflow-1`) |
| `category` | Yes | One of: Schichtplanung, Zeiterfassung, Lohnabrechnung, Abwesenheiten, Dokumente, Checklists, Analyse |
| `title` | Yes | Short title for the use case |
| `user_message` | Yes | Initial user question/prompt |
| `ai_response` | Yes | Nano's first response |
| `follow_up` | No | Object with `user_message` and `ai_response` for second turn |
| `follow_up_2` | No | Object with `user_message` and `ai_response` for third turn (e.g. vacation conflict resolution) |
| `result` | Yes | One-line summary of outcome |
| `traditional_method_time` | Yes | e.g. "6-10 Minuten" |
| `nano_time` | Yes | e.g. "20 Sekunden" |
| `time_saved_seconds` | No | Numeric value for sorting |
| `time_saved_minutes` | No | Numeric value for display |

## Date Placeholders

Use placeholders instead of hardcoded dates so content stays current:

| Placeholder | Output | Use Case |
|-------------|--------|----------|
| `__NEXT_MONDAY__` | DD.MM.YYYY (next Monday) | Shift dates |
| `__DOC_EXPIRY_1__` | DD.MM.YYYY (10 days from today) | Document expiry (full) |
| `__DOC_EXPIRY_2__` | DD.MM.YYYY (20 days from today) | Document expiry (full) |
| `__DOC_EXPIRY_3__` | DD.MM.YYYY (30 days from today) | Document expiry (full) |
| `__DOC_EXPIRY_1_SHORT__` | DD.MM. (10 days from today) | Document expiry (short) |
| `__DOC_EXPIRY_2_SHORT__` | DD.MM. (20 days from today) | Document expiry (short) |
| `__DOC_EXPIRY_3_SHORT__` | DD.MM. (30 days from today) | Document expiry (short) |

Placeholders are replaced at runtime by the conversation-cards component.

## Closing and Conclusion Best Practices

Conversations should end with a clear conclusion, not a hanging question.

- **Task-complete flows:** End with "Alles erledigt!" or similar definitive statement.
- **Optional "Kann ich sonst noch etwas für dich tun?":** Use sparingly (2-3 examples max) to avoid repetition.
- **Decision-required flows:** Add `follow_up_2` so the user chooses an option and Nano confirms completion.

## Pain-Point Mapping

Each conversation should map to a clear manager pain:

| Category | Pain Point |
|----------|------------|
| Schichtplanung | Last-minute coverage, manual availability checks |
| Zeiterfassung | Overtime compliance, manual tracking |
| Lohnabrechnung | CFO cost projection, manual reports |
| Abwesenheiten | Vacation overlap, manual conflict resolution |
| Dokumente | Compliance, missed renewals |
| Checklists | Incomplete tasks, no visibility |
| Analyse | Siloed data, manual correlation |

## Adding New Conversations

1. Add a new object to the `conversations` array.
2. Use a unique `id` (e.g. `new-use-case-1`).
3. Ensure the last AI response has a conclusion (no hanging questions).
4. Use date placeholders where applicable.
5. Run validation: `php v2/scripts/nano-ai/validate-conversation-examples.php`

## Validation

Run before committing changes:

```bash
php v2/scripts/nano-ai/validate-conversation-examples.php
```

The script checks:
- JSON syntax
- Required fields
- Unknown placeholders (warns if placeholder is not in the known list)

## Related Files

- **Data:** `docs/data/nano-ai-conversation-examples.json`
- **Schema:** `docs/data/schemas/nano-ai-conversation-example.schema.json`
- **Component:** `v2/components/nano-ai/conversation-cards-component.php`
- **Validation:** `v2/scripts/nano-ai/validate-conversation-examples.php`