Back to the Playbook
Define & DesignDD-14
How to write error messages
Write error copy together with the recovery behaviour, never promising an action the product cannot perform.
Product statusAvailable now
Input3 required inputsActual causes and available recovery actions · Product voice · Initiative focus and approved Product Brain guidance
SkillsDraft actionable error copy · Prepare task context · Review an artifact against agreed criteriaDesigner + Product Designer Agent
OutcomeError copy: per condition the trigger and placement, the exact message and action label, the rationale and open validation needs.Artifact: Error copy
Owner
Designer
Human + Agent
Participants · Agents
EngineerProduct ManagerProduct Designer Agent
Trigger
A set of user-visible failure or empty states needs copy.
Required context
CodeActual causes and available recovery actionsDesign systemProduct voiceProduct BrainInitiative focus and approved Product Brain guidance
Optional context
FilesExisting copy and character constraintsJiraRelated story
Skills
Draft actionable error copyPrepare task contextReview an artifact against agreed criteria
Suggested conversation arc
- 1Map failures and recoveryList the triggering situations, what the user loses and what recovery is actually possible. Distinguish validation, permission and system failures.Skills: Prepare task context
- 2Draft actionable messagesWrite concise wording for what happened and the next action; use familiar terms, appropriate specificity and a direct recovery link where available.Skills: Draft actionable error copy
- 3Inspect messages in the flowPlace the proposed copy in the relevant design or working screen and inspect comprehension, placement and recovery with realistic scenarios. Capture observed confusion.
- 4Confirm the state-copy contractCheck tone, consistency and technical truth, resolve confusing wording and attach the approved copy to the relevant requirement or story.Skills: Review an artifact against agreed criteria
Output
Error copy: per condition the trigger and placement, the exact message and action label, the rationale and open validation needs.
Artifacts
Creates: Error copy
What good looks like
- Every message corresponds to a concrete condition.
- Suggested recovery is supported or explicitly pending verification.
- Unknown causes are not hidden behind reassuring but false copy.
Quality gate
The Designer confirms the copy and attaches it to the story; engineering confirms the recovery behaviour.
Destination
JiraConfluence
Usually next
People and agents work from the same Product Brain. The owner stays accountable. Assigned agents prepare and check. A named person approves at the gate.
Choose the path that matches your role.
Set the Product AI direction with us, or test the shared Product Brain on real work with Jira and code.