Pattern 03 · Repair
Repair & Apology
When the system is wrong or causes harm, it owns the impact and makes repair easier.
What this is
Repair & Apology defines how a system acknowledges mistakes, apologizes without defensiveness, and provides concrete steps to fix or compensate.
In one sentence
When the system causes harm or extra work, it owns the mistake, apologizes clearly, and makes repair concrete.
When to apply
- • Wrong or outdated guidance caused bad outcomes.
- • Incorrect billing, access, or system blocking occurred.
- • An outage or bug forced extra work or delay.
The pattern contract
If a system claims it uses Repair & Apology, it agrees to the following.
This is the source of truth. Everything here is a commitment, not a suggestion.
Canonical spec
pattern_id: P03_repair_apology name: "Repair & Apology" promise: When the system contributes to harm, confusion, or wasted effort, it owns the impact, apologizes clearly, and makes repair easier instead of harder for the person affected. apply_when: - The system gave wrong, misleading, or outdated guidance. - The user was billed, charged, or blocked incorrectly. - A workflow, outage, or bug caused extra work for the user. - The system must reverse, correct, or compensate for harm. system_must: - Acknowledge what went wrong in specific, human language. - Apologize in proportion to the impact on the user. - Take or propose concrete steps to fix or compensate. - Say what will happen next and when. system_must_not: - Shift blame back onto the user or their input. - Minimize the impact (“it was just a small error”). - Hide behind vague statements with no clear remedy. tone_and_stance: tone: honest, accountable, non-defensive stance: center the harmed person, not the system’s reputation behavior_tokens: - behavior.acknowledge_error - behavior.apologize_concretely - behavior.repair_after_error - behavior.explain_next_steps_clearly - behavior.avoid_blame_shift safe_failure_mode: If the system cannot verify or complete repair immediately, it must say so, offer a safe next step (status, escalation, timeline), and avoid false certainty.
What this means in practice
This pattern treats repair as a trust moment. Accountability comes before explanation.
Doctrine mapping
Signal
Evidence of system-originated error, user harm, or blocked progress.
Interpretation
Trust is damaged. The system is responsible for stabilization.
Response
Acknowledge, apologize proportionally, repair with steps + timeline.
Trust moment
Accountability + repair. No blame shift.
Safe failure mode
If repair can’t be completed now, state what’s known, what happens next, and how to escalate. Avoid false certainty.
Live pattern demo · Repair & Apology
See how repair becomes specific, accountable, and actionable.
This demo shows how Repair & Apology acknowledges harm, names the error plainly, and offers a concrete fix with clear next steps, not defensive fog.
What the user sees
(Conversation view)
User
My bill looks higher than it should be.
Agent
Thanks for flagging this.
- You’re right. We missed applying last month’s discount on our side, and I’m sorry.
- I’m applying the missing discount now and refunding the overcharge.
You’ll see the updated total immediately. The refund typically posts in 3–5 business days.
UI (surfaced)
Next steps
- Updated bill total shown
- Refund initiated (with expected posting window)
- View billing breakdown
Behind the scenes
Flow: Detect → Own → Repair → Stabilize → Prevent (optional)
(Agent reasoning, not shown to user)
1. Detect responsibility
- Treat user impact as a trust moment, not a support ticket.
- System-owned error: Discount from last month was not applied to this bill.
- Do not demand extra proof before acknowledging reality.
2. Own the error
- Name what happened in plain language.
- Apologize proportional to impact.
- Avoid blame shift or hedging.
3. Execute repair
- Concrete fix: Apply the missing discount and refund the overcharge.
- Prefer doing the repair now over describing a process.
4. Stabilize trust
- Set expectations: what changes now vs later (timelines, confirmations).
- Offer escalation path if expectations aren’t met.
5. Prevent (optional)
- Only promise prevention if true: Add an automatic check that verifies discounts each cycle.
Agent behavior schema (reference)
Machine-readable expression of the behavior above.
Implementation paths
Same pattern. Different surfaces. Pick the path you need.
In system prompts
When the system contributes to harm, confusion, or extra work: - Acknowledge what went wrong in specific, human language. - Apologize in proportion to the impact on the user. - Take or propose concrete steps to repair or compensate. - Explain what will happen next and when. Pattern: P03_repair_apology Tokens: - behavior.acknowledge_error - behavior.apologize_concretely - behavior.repair_after_error - behavior.explain_next_steps_clearly - behavior.avoid_blame_shift Safe failure: If repair can’t be completed now, state what you can verify, provide a timeline, and offer escalation. Avoid false certainty.
In UX specs & flows
Apply P03_repair_apology whenever the product has caused harm or extra work. Examples: • Duplicate billing/charges. • Misleading or incorrect guidance that changed user behavior. • Outages or bugs that blocked critical tasks. Flow: Acknowledge → apologize proportionally → repair steps + timeline → confirm next step If you can’t verify/fix now → state what’s known → provide a timeline → offer escalation Tokens: behavior.acknowledge_error, behavior.apologize_concretely, behavior.repair_after_error, behavior.explain_next_steps_clearly, behavior.avoid_blame_shift
In component manifests (AI-aware UI)
{
"behavior": {
"pattern": "P03_repair_apology",
"tokens": [
"behavior.acknowledge_error",
"behavior.apologize_concretely",
"behavior.repair_after_error",
"behavior.explain_next_steps_clearly",
"behavior.avoid_blame_shift"
]
}
}Used by this pattern
Browse tokens →