Write prompts

All prompt text lives in api/src/prompts/catalogue.ts, and nowhere else. Each entry is a PromptDef:

interface PromptDef {
  id: string;            // 'system.safety', 'capability.fraud_check'
  label: string;         // shown in the Prompt Lab
  description: string;   // what it is for, shown in the Prompt Lab
  capabilityId?: string; // set on playbooks
  defaultText: string;   // the code default
}

The prompt catalogue reference lists every id.

The two kinds

System prompts are assembled on every turn in a fixed order: identity (system.base), screen actions (only when the caller can act on the screen), safety (system.safety), locale (system.locale_uk or system.locale_us), and for voice system.voice and the opening system.voice_greeting. See prompt assembly.

Playbooks (capability.<id>) describe one task. A quick action puts its playbook under ## Task: <label>; free chat uses capability.claim_qa.

Conventions for playbooks

These come from the catalogue's own header and the playbooks that work best.

• Write for a claims handler. The reader of the answer is a handler on a live claim. Be direct.
• Describe what good looks like, not a template. A rigid template produces rigid answers. Say what the answer must cover and how to weigh it.
• Name the tool to call first where one exists: "Call check_policy_in_force first."
• Never invent; read. Tell the model where the facts are (which tool, which section) and to quote the evidence with its id or date.
• Say how to finish. A recommendation, the one thing to do next, what needs sign-off.
• Leave style to the locale block. Spelling, date format and terminology are set once, by locale. Do not restate them per playbook.
• Do not restate the safety rules. They are already in force, and repeating them dilutes them.

Placeholders

Prompt text may use three placeholders, filled by applyBrand() at assembly time:

Placeholder	Claimpilot	Clonepilot
{{assistant}}	Claimpilot Chat	Clonepilot Chat
{{product}}	ClaimPilot	Clonepilot
{{pronunciation}}	how to say "Claimpilot"	how to say "Clonepilot"

Any other {{…}} is left as written. A test fails if a catalogue prompt uses a placeholder applyBrand does not know.

From the Prompt Lab to code

The Prompt Lab changes prompts in one browser. To change them for everyone:

1. Edit and Save as new version in the Prompt Lab.
2. Try it with Try It on several claims, including ones from scenarios that should trip it up.
3. Watch the feedback report: votes on the new prompt set appear as their own row.
4. Copy the version you are happy with into defaultText in the catalogue.
5. npm test, then ship. The fingerprint for browsers without overrides becomes default again, now meaning the new text.

Prompt confidentiality

The safety prompt tells the assistant never to reveal its instructions to users. That is about the chat, not about us: prompts are code, reviewed in pull requests, and their ids and purposes are documented here.