Implementation worksheet · 5 min read
A Failed-Action Recovery Prompt Specification
A failed-action recovery prompt needs four specified parts: a precise trigger (the specific error event plus context — which action, which object, first failure or repeat), copy that names what happened and the exact next step (never 'something went wrong'), one primary recovery action in the prompt itself (retry with the fix applied, not a link to docs), and a frequency guard (the same prompt at most once per session; repeat failures escalate to human help instead of repeating the tip). Specify these per failure mode in a table — the five failures that generate most support tickets first — and wire the prompt to the error event, not to the page.
Teams polish onboarding for the happy path and leave failures to a toast that says 'error'. But the moment after a failed action is when a user is most receptive to guidance and closest to churning — it deserves the most designed message in the product, and usually has the least.
Put it into practice
1. Rank failures by ticket volume, not error frequency
Pull 90 days of support tickets and map each to the in-product failure that caused it. The top five are your prompt backlog. High-frequency errors users self-recover from (typo in email) don't need prompts; low-frequency ones that generate tickets (CSV import column mismatch) desperately do.
2. Specify the trigger with context, not just the error
'Import failed' is a page-level toast. 'Import failed because column headers didn't match, first attempt, file had >0 rows' is a promptable moment with a knowable fix. The trigger spec names event + properties + attempt count.
3. Write copy that names the fix, not the apology
Three sentences maximum: what didn't happen, why (in the user's words, not the stack trace's), what to do now. The test: could the user act without leaving the prompt? If the copy says 'please try again later', you don't have a recovery prompt — you have an outage notice.
4. Put the recovery action in the prompt
Retry-with-fix beats link-to-docs: 'Map your columns' opens the mapper pre-filled, not an article about mappers. Every click between prompt and fix loses users to the tab close.
5. Guard frequency and escalate repeats
Same prompt once per session; second identical failure offers human help ('this usually means X — talk to us') instead of the same tip louder. Repeating a failed suggestion trains users that prompts are noise.
Recovery prompt spec (one row per failure mode)
Copy this structure into your review document and record your observed result for each row.
| Failure event | Trigger context | Prompt copy (what/why/next) | Recovery action | Repeat behavior |
|---|---|---|---|---|
| import_failed | header mismatch, attempt 1 | named columns + fix | open mapper pre-filled | attempt 2 → offer help |
| invite_bounced | invalid domain | named address + correction | edit + resend inline | 2nd bounce → suggest SSO check |
| payment_failed | card declined | named reason if known | update card inline | 2nd fail → support link |
| publish_blocked | missing required field | named field | focus the field | — |
| integration_error | auth expired | named integration | reconnect flow | 2nd fail → status page + help |
A failure worth checking
The blame trap: copy that makes the failure the user's fault ('you entered an invalid file'). Users who feel blamed don't retry — they close the tab and tell your NPS survey about it. The same information lands as help when the subject is the system: 'That file's headers don't match the template — here's the mapper.' Audit every failure message for its grammatical subject; it predicts the retry rate.
Common questions
Should recovery prompts be modals or inline?
Inline, anchored to the failed action, unless the failure blocks everything (payment, auth). A modal for a fixable field error punishes the user twice — once with the failure, once with the interruption.
How do we measure whether a recovery prompt works?
Retry-success rate after prompt exposure vs before it existed, and ticket volume for that failure mode. Prompt views are meaningless; recovered users are the metric.
Basis and scope
This is a proposed implementation method using illustrative examples, not a measured benchmark or a customer case study. Prepared with AI assistance. Validate product-specific behavior against current documentation and your own test environment.