version: "1.0.0" name: ai-ux-patterns description: The UX patterns that don't exist in deterministic software — confidence display, graceful failure, reversibility, human-in-the-loop, and progressive disclosure — for designing trustworthy probabilistic features. Grounded in Google PAIR (People + AI Guidebook) and Apple HIG for ML. Turns "how should the AI feature behave when it's unsure or wrong" from ad-hoc choices into a checklist. when_to_use: | Use when:

• spec-writer is specifying any feature where an LLM/ML model produces user-facing output
• the feature can be wrong, unsure, or slow, and the user must be able to trust, verify, or correct it
• designing async "thinking/processing" states, confidence surfaces, or undo/override flows
• user-researcher is testing whether users trust (or are misled by) an AI feature
• an agent acts on the user's behalf and the autonomy/approval level must be decided

allowed-tools: Read, Write

AI UX patterns — designing for non-determinism

Deterministic software gives the same output for the same input, every time. UX assumes the system is right. AI features are probabilistic: they are sometimes wrong, sometimes unsure, and sometimes slow — and the UX must be designed around that uncertainty, not in spite of it.

Google's People + AI Research (PAIR) guidebook and Apple's Human Interface Guidelines for machine learning converge on the same core: the job of AI UX is earning and calibrating trust under uncertainty. Four patterns do most of the work — confidence signals, graceful failure, reversibility, human-in-the-loop — plus progressive disclosure to keep control from becoming overwhelm.

This skill is the trust & uncertainty layer for probabilistic features. It complements hooked-ux (the habit loop for any product); it does not overlap it.

The mental model: calibrated trust

The failure mode at both extremes:

• Over-trust — the UI projects false confidence, the user stops

checking, the model is wrong, and the cost lands on the user. Erodes trust permanently the first time it bites.

• Under-trust — the UI hedges on everything, asks for approval

constantly, surfaces uncertainty the user can't act on. The user concludes the feature is useless and turns it off.

Good AI UX calibrates: confident where the system has earned it, honest where it hasn't, and always recoverable. Trust is built progressively — start cautious, earn autonomy.

Pattern 1 — Confidence signals

What: surface how reliable a given output is, so the user knows when to lean on it and when to check.

When/why: any time output reliability varies meaningfully across cases (extraction, categorization, recommendations, generated answers). The user needs to allocate their attention to the cases that need it.

How:

• Per-field, not just per-response in extraction flows — mark the

fields the system is sure about differently from the fields it guessed (e.g., a guessed merchant name visually flagged for review while a parsed amount is shown plainly).

• Calibrate the signal — "85% confident" must actually mean ~85%

right over many cases, or the number is worse than none (this is where ai-evals calibration work feeds the UX).

• Prefer plain-language or visual confidence ("Looks right" /

"Please check") over raw probabilities for consumer audiences; reserve numeric scores for expert users who can act on them.

Anti-patterns:

• False precision — "97.3% confident" from an uncalibrated model.
• Hiding uncertainty entirely — showing every guess as fact; the

first wrong "fact" on something that matters costs disproportionate trust.

• Uniform confidence — one badge for the whole response when some

fields are certain and others are guesses.

Pattern 2 — Graceful failure (the degradation hierarchy)

What: when the best AI path fails or is low-confidence, fall back down a hierarchy rather than dead-ending the user.

When/why: AI will fail — bad input, model unsure, service down, timeout. PAIR's guidance: design for graceful failure and always give the user a way forward.

The degradation hierarchy:

Full AI response
   ↓  (low confidence / partial failure)
Simplified AI response  (narrower, safer claim)
   ↓
Rule-based / deterministic response  (known-good fallback)
   ↓
Human handoff or manual control  (user does it themselves, with help)

Every failure should land the user on the next rung down — never on a blank screen or a spinning wheel of death. Concretely: "Try rephrasing," "Choose from these options," "Edit it directly," "We left this for you to categorize" are all valid landings.

Anti-patterns:

• Dead-end errors — "Something went wrong" with no next action.
• Binary success/failure — "AI did it" or "AI failed" with no middle

tier, when a simplified or rule-based answer was available.

• Silent wrong-guessing — guessing confidently rather than degrading

to "I'm not sure, here are options."

Pattern 3 — Reversibility

What: every AI action must be trivially easy to undo or correct.

When/why: reversibility is what makes occasional wrongness tolerable. If the user knows a mis-categorization or a bad edit is one tap to fix, they will forgive the model being wrong sometimes — and they will use the feature instead of fearing it. Irreversible AI actions force the user to verify everything up front, which destroys the time savings the AI was supposed to provide.

How:

• One-tap undo / re-edit on any AI-applied change.
• The correction should teach the system — a user override is the

highest-quality training signal there is; capture it.

• Make the current AI decision visible and editable, not buried.

Anti-patterns:

• Irreversible auto-apply — the AI commits a change the user can't

cleanly back out of.

• Correction that doesn't stick — the user fixes it, and the system

re-overrides them next time (a trust-killer; see the Acme example).

• Hidden state — the user can't even see what the AI decided, so

they can't correct it.

Pattern 4 — Human-in-the-loop → human-on-the-loop (the autonomy dial)

What: how much the system does autonomously vs how much it asks the user to approve — and the fact that this should move over time.

When/why: autonomy is not the absence of control; it is control applied sparingly and intelligently. The right setting depends on two things: how proven the system is on this task, and how high the stakes are.

The dial:

• Human-in-the-loop (approve before acting) — when the system is

unproven on this task, or the stakes/irreversibility are high. The user is in the path.

• Human-on-the-loop (act, but surface for review) — once the system

has proven reliable on a task. The user supervises rather than approves each one.

• Re-tighten — if the system starts making questionable calls,

move back toward in-the-loop. The dial turns both ways.

A clean way to set the initial position: map error frequency × error severity on a 2×2. High-severity or high-frequency errors → keep the human in the loop. Low-low → safe to automate and just surface for review.

Anti-patterns:

• Over-prompting — asking approval for things the system is reliably

right about; the user learns to rubber-stamp, which defeats the point.

• Under-gating high stakes — auto-acting on irreversible or

high-cost decisions before earning the right to.

• A fixed dial — never loosening as trust is earned (feature feels

tedious forever) or never tightening when quality drops.

Pattern 5 — Progressive disclosure

What: reveal AI complexity, controls, and explanation on demand, not all at once.

When/why: the patterns above add controls — confidence, overrides, approvals, explanations. Dumped on screen together, they overwhelm. Show the simple confident path by default; let the user drill into "why did it say this?", "what else could it be?", and fine-grained controls only when they want them.

How:

• Default view: the answer + a light confidence cue.
• One tap deeper: alternatives, the reason, the edit control.
• Power controls (rules, automation thresholds) behind settings, not in

the main flow.

Anti-patterns:

• Control overload — every knob visible at once.
• Zero disclosure — a black box with no "why" available even on

request (kills trust for the users who want to verify).

Worked example — Acme's "Categorizing…" experience

Acme maps cleanly onto all five patterns, turning instructions.md §3/§6/§7 from scattered rules into a coherent trust design:

1. Confidence (Pattern 1). Auto-categorized transactions surface

their certainty. An exact-match (gate 1) or regex (gate 2) hit is shown plainly, no fuss — the system has earned it. A low-confidence LLM guess (gate 4–5) is visually flagged "please check" and batched into a review queue. Confidence comes straight from which gate decided it, plus the vector cosine score (>0.85 threshold).

1. Graceful failure (Pattern 2). The decision hierarchy is the

degradation hierarchy: exact-match → regex → vector → LLM → leave uncategorized for the user rather than guess wildly. A failed PDF parse degrades to "we couldn't read this statement — try a CSV or review manually," never a dead end. The async "Categorizing…" state (the Mac Mini queue, §3) is itself graceful: the UI stays fully responsive while inference happens elsewhere, showing "Processing" instead of freezing.

1. Reversibility (Pattern 3). §7's "user override is absolute" is the

reversibility pattern as product law: one-tap re-bucket, and the correction instantly updates the exact-match table so the system never re-overrides that user's decision again. The override is both the undo and the training signal.

1. Human-in-the-loop (Pattern 4). The autonomy dial is set by

confidence: high-confidence categorizations auto-apply (human-on-the-loop — surfaced in the feed, not gated); low-confidence ones wait for confirmation (human-in-the-loop). As the user's exact-match table fills in, more transactions auto-apply — the dial loosens as trust is earned, exactly as the pattern prescribes.

1. Progressive disclosure (Pattern 5). Default feed shows the

category + a light confidence cue. Tap a transaction to see why it was categorized, what else it might be, and the re-bucket control. The natural-language rule engine (§7, "put late-night food under ₹500 into Cravings") lives behind settings, not in the main feed.

The skill turns each of these from "someone's UX taste" into a checklist the spec must satisfy before an AI feature is build-ready.

When to use vs when NOT to

Use when:

• Any feature where a model's output is user-facing and can be wrong.
• Designing async "thinking" states, confidence surfaces, undo flows, or

agent-approval flows.

• Researching whether users trust — or are misled by — an AI feature.

Do NOT use (or down-weight) when:

• The feature is deterministic — a normal calculation, a CRUD form, a

hard-coded rule. Confidence badges on certain outputs are noise.

• The model output is never shown to or acted on by a user (purely

internal scoring with no UX surface).

• You're choosing the habit/engagement loop — that's hooked-ux, not

this skill (though they layer well together).

Pitfalls

1. Hiding uncertainty — projecting false confidence; the first wrong

"fact" on something that matters costs trust out of all proportion.

1. Dead-end failures — no next action when the AI can't deliver; the

degradation hierarchy exists precisely to prevent this.

1. Irreversible AI actions — no easy undo, so users must verify

everything up front, erasing the time savings.

1. Correction that doesn't stick — overriding the user's manual fix

later; the single fastest way to lose a user's trust in an AI feature.

1. Over-prompting for approval — gating things the system is

reliably right about; users learn to rubber-stamp.

1. Control overload — every knob and explanation on screen at once

instead of progressive disclosure.

1. Uncalibrated confidence — a "92%" badge that isn't actually right

92% of the time is worse than showing no number at all.

Ethical boundary

Confidence display is an honesty obligation, not a decoration. A product must not show high confidence it has not earned, must not hide uncertainty to seem more capable, and must not make an AI action irreversible to inflate engagement or lock the user in. On anything that affects the user's money, health, safety, or legal standing, the bias must be toward surfacing uncertainty and preserving the user's control, even at the cost of a less "magical" demo. Dark patterns that exploit trust in AI — fake certainty, buried undo, sticky auto-apply — are out of bounds.

Cross-links

• `ai-evals` — produces the calibrated confidence scores Pattern 1 displays; UX is only as honest as the eval underneath.
• `responsible-ai-guardrails` — the safety side of failure handling (block/escalate); this is the UX side (degrade/recover).
• `ai-use-case-scoping` — decides whether the feature should be AI at all; sets the stakes that tune the autonomy dial.
• `accessibility` — confidence cues and error states must not rely on color alone; degraded states need accessible affordances.
• `hooked-ux` — the habit loop these trust patterns sit inside; complementary, not overlapping.

References

• Google PAIR — People + AI Guidebook (patterns for trust, mental models, feedback & control, errors & graceful failure) — https://pair.withgoogle.com/guidebook/
• Apple — Human Interface Guidelines: Machine Learning (mistakes, calibrating trust, multiple options, corrections) — https://developer.apple.com/design/human-interface-guidelines/machine-learning
• DesignKey Studio — "Designing for Trust: UX Patterns for AI Features" (PAIR-grounded) — https://www.designkey.studio/post/designing-for-trust-ux-ai-features
• Clearly Design — "Designing for AI Failures: Error States and Recovery Patterns" — https://clearly.design/articles/ai-design-4-designing-for-ai-failures
• CoCreate — "Probabilistic UX Design: Designing for AI Uncertainty and Confidence" — https://cocreate.consulting/field-notes/probabilistic-ux-design-patterns
• ByteBridge — "From Human-in-the-Loop to Human-on-the-Loop: Evolving AI Agent Autonomy" — https://bytebridge.medium.com/from-human-in-the-loop-to-human-on-the-loop-evolving-ai-agent-autonomy-c0ae62c3bf91

The honesty filter

If the AI feature's UX assumes the model is always right, the spec is not done — it is a demo script. A build-ready AI feature has answered, on paper: What does the user see when it's unsure? When it's wrong? How do they fix it in one tap? When does it act without asking, and when does it ask? If those four questions have no answer, the feature is not ready, no matter how good the happy path looks.

<!-- provenance: great-pm-original 2026-05-29; grounded in cited sources (Google PAIR, Apple HIG for ML, Clearly Design, CoCreate, ByteBridge). -->