quill: error message style guide v1.0 draft

wizard-work/quill/error-message-style-guide-1.0-draft.md

@@ -0,0 +1,88 @@
+DRAFT: USER-FACING ERROR MESSAGE STYLE GUIDE
+Version: 1.0-draft
+Author: Quill (Draft lane)
+Date: 2025-10-28
+Status: Ready for review
+
+---
+
+## 1. Purpose
+
+This guide sets the minimum standard for all user-facing error text in products owned by the troupe. It covers:
+- In-app error banners and toasts
+- API error response bodies
+- CLI stderr messages
+- Email notifications about failures
+
+It does not cover: log lines, internal monitoring alerts, or debug output.
+
+## 2. Core Rules
+
+Rule 1 — Say what happened, not what the system did.
+  Bad: "An error has occurred."
+  Good: "Your payment could not be processed."
+
+Rule 2 — Say what the user can do next, or say nothing.
+  Bad: "An unexpected error occurred."
+  Good: "Retry in 2 minutes, or contact support@example.com."
+  If no action is reasonable, write: "Something went wrong on our side. We are investigating."
+
+Rule 3 — One sentence per message unless the next sentence is a concrete action.
+  Max length: 140 characters for toasts/banners; 300 characters for email bodies.
+
+Rule 4 — No jargon unless the audience is the technical user explicitly.
+  Bad: "NullPointerException in commit phase."
+  Good (for end user): "We could not save your changes."
+  Good (for technical user): "NullPointerException during commit phase (ID: abc123)."
+
+Rule 5 — Tone: calm, direct, no exclamation marks.
+  Bad: "Oops! Something broke!"
+  Good: "Your upload failed."
+
+## 3. Phrase Bank
+
+Use these exact phrases where applicable:
+- "Your [thing] could not be [action]."
+- "We could not [action] your [thing]."
+- "Try again. If it keeps failing, contact [support channel]."
+- "Something went wrong on our side. We are investigating."
+- "[Thing] is temporarily unavailable."
+
+Avoid:
+- "An error occurred"
+- "Oops"
+- "Sorry for the inconvenience"
+- "Please try again later" (only if there is a known time bound)
+
+## 4. Anti-patterns
+
+1. Blaming the user without evidence.
+   Bad: "You entered an invalid file."
+   Good: "The file format is not supported."
+
+2. Stack traces in user channels.
+   Never send raw tracebacks to end users.
+
+3. Multiple errors in one message.
+   One root cause per message. Aggregate in a report if needed.
+
+## 4. Checklist (ship-gate)
+
+Every new or changed error message must pass:
+- [ ] Says what happened in plain language.
+- [ ] States one concrete action or says nothing.
+- [ ] Is under the character limit for its surface.
+- [ ] Has no jargon for the intended audience.
+- [ ] Uses calm tone, no exclamation marks.
+- [ ] Was read aloud once to catch awkward phrasing.
+
+## 5. Measurement
+
+Track weekly:
+- % of user-facing error messages that include a concrete action.
+- Mean character count per message surface (toast, email, API).
+- Support ticket volume for the top 5 error messages.
+
+## 6. Change log
+
+- 1.0-draft (2025-10-28): Initial draft.