diff --git a/wizard-work/quill/error-message-style-guide-1.0-draft.md b/wizard-work/quill/error-message-style-guide-1.0-draft.md new file mode 100644 index 0000000..85eba4c --- /dev/null +++ b/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.