Prompt Design

# Prompt Design — Closira AI Customer-Support Workflow

This document explains every prompt the workflow sends to the model, **and the
reasoning behind each design choice**. The business it operates for is the
fictional **Bloom Aesthetics Clinic** (an extended version of the sample SOP
in the assignment). The complete machine-readable SOP lives in
[`data/sop.json`](data/sop.json); all prompts are defined in code in
[`src/prompts.py`](src/prompts.py).

The guiding principle throughout: **the model is a careful front-desk
assistant, not an oracle.** It is rewarded for staying inside the SOP and for
honestly handing off when it cannot help — never for sounding confident.

---

## 1. Architecture: why prompts are split per stage

A single mega-prompt that tries to answer, qualify, detect anger, and
summarise at once is hard to reason about and hard to keep reliable. Instead
the workflow uses **one focused prompt per job**:

| Prompt | Stage | Job |
|---|---|---|
| `faq_system_prompt()` | 1 — FAQ | Answer a question from the SOP only |
| `escalation_classifier_prompt()` | 3 — Escalation | Decide if a human is needed |
| `qualification_summary_prompt()` | 2 — Qualification | Turn raw answers into a lead record |
| `summary_system_prompt()` | 4 — Summary | Produce the end-of-session summary |

Each prompt is single-purpose, which makes it shorter, easier to test, and
harder to distract. Crucially, **escalation detection is its own prompt that
runs before answer generation** — safety is not left to the same model call
that is also trying to be helpful.

Every prompt instructs the model to **reply with JSON only**. This is the
backbone of the reliability design: the Python layer reads explicit fields
(`confidence`, `escalate`, `answered_from_sop`) and makes deterministic
decisions, instead of trying to interpret free-form prose.

---

## 2. The full system prompt (Stage 1 — FAQ Answering)

This is the primary customer-facing prompt. It is assembled from three
parts — a persona block, a grounding-rules block, and a task block — and the
**entire SOP is embedded verbatim** at the end.