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

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.