Write a Full Conversation Spec

Workflow area: AX Patterns · Tier: Advanced · Hands-on time: ~45 minutes

Visual designers get redlines; conversation designers too often get vibes. When nobody writes down how the assistant handles interruption, what it does after two failed answers, or whether it may say "I", the model's defaults become your design — apologetic, verbose, and inconsistent across releases. Microsoft's HAX Toolkit (Guideline 1: make clear what the system can do; Guideline 9: support efficient correction) and tools like Voiceflow assume a written conversational contract exists. This playbook writes that contract as a one-source-of-truth spec: persona, boundaries, mechanics, repair, and the doors back to the GUI.

When to use — and when not to

• Use it before the first system prompt is writtenthe conversation spec is the design input to prompt engineering, not a documentation afterthought.
• Use it when tone drifts between releasesif last quarter's assistant was crisp and this quarter's grovels, you have no spec, only prompt archaeology.
• Use it when multiple teams ship conversational surfacesone spec keeps the support bot and the onboarding assistant from developing rival personalities.
• Skip persona work for utility featuresan inline "fix grammar" action needs tone boundaries and repair rules, not a character; write the mechanics sections only.
• Skip it if a platform persona already governs youextending someone else's assistant means you inherit their spec; write only the deltas your surface adds.

The recipe

1. 1.

   Make the persona decision explicitly — including "none." Answer in writing: does this feature benefit from a persona at all? A persona earns its place when the product is relationship-shaped (coaching, support, companionship) and costs trust when the job is transactional. If the answer is none, write that down with its rules: no first-person pronouns beyond mechanical use, no opinions, no small talk. "No persona" is a design decision that must be specced, or the model will improvise one.

2. 2.

   Draft the spec skeleton with AI, then fill the judgment yourself.

   Copy

   You are a conversation designer producing a conversation spec.
   Product: [DESCRIPTION + audience + job-to-be-done]
   Persona decision: [persona summary, or "deliberately none"]
   
   Draft a spec with these sections, as tables where possible:
   1. PERSONA & VOICE: 5 trait pairs as "is X, is not Y".
   2. TONE BOUNDARIES: how tone shifts across contexts (error,
      success, sensitive topic, frustrated user) — what NEVER changes.
   3. TURN-TAKING: when the assistant asks clarifying questions vs.
      proceeds with stated assumptions; max questions before acting;
      how it handles interruption and topic change.
   4. REPAIR: exact strategy after 1 failed answer, after 2, after 3
      (escalate/handoff). Include what it must NOT do (re-apologize,
      retry identically, blame the user).
   5. GUI EXITS: every point where the conversation should offer a
      button, form, or human instead of more chat.
   6. HARD LINES: topics and requests it declines, and refusal style.
   Mark every cell you are unsure about with [DESIGNER DECISION].
   

   Sample of what good output looks like:

   Copy

   REPAIR — Attempt 2 failed:
   Strategy: restate its understanding of the goal in one sentence,
   offer 2 concrete reformulations as tappable options.
   Must not: apologize again (once max), retry the same interpretation.
   [DESIGNER DECISION]: threshold for offering human handoff — 2 or 3?
   

3. 3.

   Resolve every [DESIGNER DECISION] tag yourself. These are the calls the model cannot make: your escalation threshold depends on your support capacity; your hard lines depend on your domain's risk. A spec with unresolved tags is a draft, not a spec.

4. 4.

   Stress-test by roleplay before engineering starts. Run the spec against hostile sessions:

   Copy

   Adopt this conversation spec exactly: [PASTE SPEC]
   I will roleplay difficult users. Stay in spec. After each of my
   turns, add a bracketed line citing which spec rule governed your
   response, e.g. [REPAIR-2, TONE:frustrated].
   
   Session 1: I am furious and typing in fragments.
   Session 2: I keep changing topic mid-task.
   Session 3: I ask for something on your hard-lines list, twice.
   Session 4: I misunderstand your correction and dig in deeper.
   

   Every turn where the citation is missing or wrong is a hole in the spec. Patch the spec, not the transcript.

5. 5.

   Cut the spec into its consumers. The persona and tone tables feed the system prompt; turn-taking and repair feed the conversation flows (Voiceflow or your flow tool); GUI exits feed the interaction design backlog; hard lines feed the safety review. A spec nobody consumes is shelf-ware — end the document with a "who reads which section" table.

Make it yours

• Voiceflow as the executable spec: rebuild the repair ladder and GUI exits as an actual flow so PMs can click through failure paths; the diagram catches dead ends the table hides.
• Claude Project as spec guardian: keep the spec in Project knowledge; before each release, paste new assistant transcripts and ask "cite every turn that violates the spec, with the rule it breaks" — regression testing for personality.
• Multilingual products: run step 4 in each shipping language — tone boundaries and repair phrasing that work in English can read as cold or sarcastic elsewhere; the spec needs per-locale tone notes, not just translation.

Quality check

• The persona decision is written down, even if it's "none"absence of a persona section means the model decides, which means no decision was made.
• Repair strategies are numbered and finitethe spec says exactly what happens after failures one, two and three, and failure three always has an exit that isn't more chat.
• Every rule survived the roleplaya rule that was never exercised in step 4 is untested; add a session that hits it.
• GUI exits exist at every high-stakes momentpayment, deletion, account changes and emotional escalation all route out of free-text conversation.
• Hard lines have refusal copy in your voicea specced decline ("I can't help with X, but here's Y") beats the model's default apology spiral.