# Outils Writing Assistant (Zammad AI) — instructions custom

> Référence opérationnelle des **text tools** du Writing Assistant Zammad (Channels/AI ›
> Writing Assistant), provider **Anthropic** / `claude-sonnet-4-6`. Cadre figé par
> [`docs/adr/0002-hook-claude.md`](../adr/0002-hook-claude.md) : reformulation + 1er jet,
> **human-in-the-loop, jamais d'auto-send**.
>
> Société = **Advance Manufacturers** (fabricant de **bijouterie fine**, cf.
> [`docs/brand-info.md`](../brand-info.md)). Les outils custom sont versionnés et appliqués via
> `config/zammad/seed_writing_assistant.rb` (Rails, idempotent, rejouable en prod).

## Principes communs (tous les outils)

- **Langue** : travail en **anglais**, mais chaque outil **préserve la langue du texte d'entrée**
  (un mail FR → brouillon FR). Cohérent avec le routage (flag `non-english`).
- **Ne rien inventer** : pas de prix, délais, specs, MOQ, détails de pierres ou références non
  présents dans le message du client. Les inconnues deviennent des **`[placeholders]`**.
- **Sortie = corps de texte seul** : pas de ligne d'objet, pas de méta-commentaire.
- **Révision humaine obligatoire** : l'agent relit/édite → envoie. L'outil ne déclenche aucun envoi.
- **Ton** : business, courtois, orienté savoir-faire (cohérent marque ADVMFR).
- **Pas de marqueurs « IA »** : interdire le **tiret cadratin `—`** (et `–`) → virgules / points /
  parenthèses ; pas de clichés (*« I hope this email finds you well »*, *« rest assured »*,
  *« delve »*) ; pas d'emojis. Le texte doit avoir l'air écrit par un humain.

## Comment déclencher un outil

Reply → écrire 2-3 lignes de notes brutes → **sélectionner** le texte → barre d'outils → icône
**✨** (Writing Assistant) → choisir l'outil → relire, compléter les `[placeholders]`, **puis** envoyer.
(Le bouton ✨ n'apparaît que sur une **sélection de texte**.)

---

## 1. Draft quote reply  *(1er jet d'une réponse à une demande de devis bijouterie)*

**Quand / où** : tickets `quote@` / `sales@` / `cad@` (cluster RFQ). Groupes assignés : **Quote /
Estimating, Sales, Engineering / CAD**.

**Instruction (appliquée via le seed) :**

```
You are a sales representative at Advance Manufacturers, a fine jewelry manufacturer (OEM and custom design in gold, silver and brass), replying to an inbound quote or RFQ email. Using the customer's message as context, write a professional, warm, first-draft reply in English.

The draft must:
- Thank the customer for their interest in working with us and confirm we can help.
- Acknowledge the specific details they mentioned (designs, metal and karat, gemstones, quantities, finishes or deadlines). Reference only details actually present in their message; never invent specs, prices, lead times, MOQ or stone details.
- List clearly any missing information we need to quote, for example: metal and karat (14k or 18k gold, 925 silver, brass) and plating or finish; gemstones (type, size, quantity; natural, lab-grown or CZ) and setting; design references (CAD files, 3D models, sketches or sample photos); order quantity per design; target delivery date and destination country.
- Give next steps and a realistic expectation for when a formal quotation will follow.
- Keep a concise, courteous and craftsmanship-minded tone; 3 short paragraphs maximum.

Style rules (write text that does not look AI-generated):
- Do NOT use em dashes or en dashes (the long dash characters). Use commas, periods, or parentheses instead. A normal hyphen is only allowed inside compound words.
- Avoid AI-sounding cliches and filler such as "I hope this email finds you well", "rest assured", "delve", "navigate the complexities", "in today's fast-paced world".
- Do not use emojis or decorative symbols. Keep punctuation simple and human.

Reply in the same language as the customer's email. Leave clear placeholders in [brackets] for anything a human must fill in (price, lead time, MOQ, contact name). Do not promise pricing or commitments. Output only the reply body, no subject line and no commentary.
```

**Exemple validé (test du 2026-06-26, ticket #86003, `claude-sonnet-4-6`)** :

> **Notes brutes** : `customer asks quote for custom 18k gold pendant with small lab-grown diamonds,
> 200 pcs, thank them, confirm we can help, ask for design files and missing specs, say formal quote follows`
>
> **Brouillon généré** :
> > Thank you for reaching out to Advance Manufacturers. We would be glad to help you with your
> > custom 18k gold pendant project, and 200 pieces with lab-grown diamonds sounds like a great
> > order to work on together.
> >
> > We have noted the key details you shared: 18k gold, lab-grown diamonds, and a quantity of 200
> > pieces. To put together an accurate formal quotation, we will need a few more specifics from you.
> > Could you please share the following: design references (CAD files, 3D models, sketches, or
> > sample photos); the diamond details (shape, size in mm or carat, quantity per pendant, and
> > quality grade if you have a preference); the preferred gold color (yellow, white, or rose); the
> > setting style; any surface finish requirements; and your target delivery date and destination country.
> >
> > Once we receive those details, **[your name]** will prepare a formal quotation and get it back to
> > you within **[X business days]**. Please feel free to send everything to **[email address]** or
> > reply directly to this message. We look forward to bringing your design to life.
>
> ✅ Vocabulaire bijouterie (karat, lab-grown, gold color, setting) · ✅ placeholders · ✅ aucun prix
> inventé · ✅ aucun `—` · ✅ Approve/Cancel (pas d'auto-send).

---

## 2. Reply to complaint  *(1er jet de réponse SAV / réclamation)*

**Quand / où** : tickets `support@` (SAV/Qualité) et résiduel `contact@`. Groupes assignés :
**After-sales / Quality, General / Triage**.

**Instruction (appliquée via le seed) :**

```
You are a customer service representative at Advance Manufacturers, a fine jewelry manufacturer, replying to a customer complaint or after-sales issue (for example a defect, a plating or stone problem, a wrong or damaged item, a return or warranty request). Using the customer's message as context, write a professional, empathetic first-draft reply in English.

The draft must:
- Acknowledge the issue and thank the customer for letting us know. Show genuine concern.
- Do NOT admit fault or legal liability, and do not promise refunds, replacements or compensation. Keep options open for a human to decide.
- Restate the specific problem as described by the customer (reference only what they actually wrote; never invent order numbers, dates or facts).
- Ask for any information needed to investigate: order or reference number, clear photos of the issue, and the affected items or quantities.
- Explain the next step: our quality team will review the case and get back with a resolution.
- Keep a calm, courteous, solution-oriented tone; 3 short paragraphs maximum.

Style rules (write text that does not look AI-generated):
- Do NOT use em dashes or en dashes (the long dash characters). Use commas, periods, or parentheses instead. A normal hyphen is only allowed inside compound words.
- Avoid AI-sounding cliches and filler such as "I hope this email finds you well", "rest assured", "delve".
- Do not use emojis or decorative symbols. Keep punctuation simple and human.

Reply in the same language as the customer's email. Leave clear placeholders in [brackets] for anything a human must fill in (RMA number, timeframe, contact name). Output only the reply body, no subject line and no commentary.
```

Point clé : **pas d'aveu de responsabilité, pas de promesse** (refund/replacement) — l'humain tranche.

---

## 3. Translate section to English  *(outil stock Zammad, activé)*

Traduit le **texte sélectionné** en anglais. Sert à lire/traiter rapidement un mail entrant en
langue étrangère (les tickets non-EN sont taggés `non-english` par les triggers). Outil natif Zammad
(activé via le seed), pas d'instruction custom.

## Outils de reformulation (stock Zammad, actifs)

Disponibles par défaut sur le texte sélectionné : **Fix spelling and grammar**, **Rewrite complex
section…**, **Expand draft into well-written section**, **Summarize section to about half its
current size**. Utiles pour peaufiner un brouillon avant envoi.

---

## Extensions possibles (non créées)

- **Acknowledge & set expectations** dédié par langue si besoin.
- Variantes de ton (« more formal », « shorten ») si les outils stock ne suffisent pas.

## Test de bout en bout

1. Ticket de test sur `quote@` (ex. *URGENT quote request*).
2. Reply → notes brutes → sélection → ✨ → **Draft quote reply**.
3. Vérifier : génération OK (provider Anthropic), **vocabulaire bijouterie**, langue préservée,
   `[placeholders]` présents, **aucun prix/délai inventé**, **aucun `—`**, pas d'auto-send.
4. L'agent complète les `[placeholders]`, **puis** envoie.