💡 Avatar Decision Replay: Post-Hoc Explainability Through Conversational Audit Narration

[github-actions[bot]]

Summary

After completing a workflow, the user can say "walk me through how you did that" and the avatar replays key decision points from the session's audit trail, explaining in plain language what it chose, what alternatives it considered, and why it made each decision. This transforms the audit log from a compliance artifact into a trust-building, educational tool. The avatar narrates a structured "decision journey" with pause points where the user can ask follow-up questions, serving EU AI Act explainability requirements while making AI decision-making transparent to non-technical users.

Market Signal

Only 21% of organizations have runtime visibility into what their AI agents actually do. EU AI Act explainability mandates require that users understand AI decision processes. ChatGPT Voice Desktop (shipped July 2026) and Gemini Desktop provide no mechanism for users to understand HOW the agent arrived at its output — they deliver results without reasoning transparency. Explainable AI (XAI) is identified as the "missing link between experimentation and large-scale enterprise adoption." The gap between what agents DO and what users UNDERSTAND is widening as agent capabilities grow.

Sources: Enterprise Guide to AI Agent Audit Trails, Explainable AI Enterprise Guide (Seekr), AI Agent Governance 2026 (Zylos)

User Signal

TalkTerm's target user Sarah (PM) produces artifacts but can't verify the agent's reasoning. When she shares output with her team, they ask "why did it choose this approach?" and she can't answer. Existing idea #324 (Deliberation Mode) addresses the avatar as a thinking partner DURING execution, and #231 (Shareable Session Summaries) addresses visual replays of session activity. But neither addresses POST-HOC explainability — the avatar walking back through its completed reasoning in a conversational, interruptible way that non-technical users can follow and interrogate.

This also connects to the project's core design principle: "Power through simplicity — Full agent capability is accessible but invisible. Users see decisions and results, never machinery." Decision Replay makes the invisible visible — but only when the user asks.

Technical Opportunity

TalkTerm's audit trail architecture (FRs 27-29) captures timestamp, action type, outcome, and triggering intent for every agent action. Decision Replay extends this by:

1. Decision-point annotations — mark audit entries where the agent chose between alternatives during execution
2. Alternative storage — capture considered-but-rejected options with brief rationale at each decision point
3. Replay mode — a new mode in the Agent bounded context that re-reads the annotated audit trail sequentially
4. Avatar narration templates — convert structured decision data into conversational explanations ("At this point, I had three options: A, B, and C. I recommended B because...")
5. Interactive pause points — user can interrupt replay to ask follow-up questions about any decision

The AuditRepository port gains a query method for decision points; the avatar's speaking state machine handles the replay narration with its existing listening/speaking/thinking states.

Assessment

Dimension	Score	Rationale
Feasibility	high	Builds on planned audit trail (FRs 27-29). Decision-point annotations and narration templates are additive, not architectural changes. Avatar state machine already supports the required speaking patterns.
Impact	med	Unique trust-building mechanism. Addresses the explainability gap (21% visibility). Supports EU AI Act compliance. Differentiates from every competitor's "black box" approach.
Urgency	med	EU AI Act creates regulatory pressure. Enterprise adoption depends on explainability. But core audit trail must be built first — this extends it.

Adversarial Review

Strongest objection: If the underlying LLM doesn't expose its true reasoning (chain-of-thought is often summarized or filtered), the "replay" will be a post-hoc rationalization, not genuine explainability. Users might develop false confidence in explanations that don't reflect actual decision processes.

Rebuttal: TalkTerm's avatar already hides intermediate thinking (FR22) and presents only final results. Decision Replay doesn't claim to expose raw chain-of-thought — it narrates the OBSERVABLE decision trail: what options were presented, what the user chose, what the agent recommended, and what happened next. This is the level of explainability the EU AI Act requires and that non-technical users actually want. It's analogous to a project manager explaining a decision log — factual, sequential, and actionable — not a neuroscience explanation of how their brain works. The audit trail captures real events, not fabricated reasoning.

Suggested Next Step

Define the decision-point annotation schema for the audit trail (what constitutes a "decision point," what metadata to capture). Design the replay narration template system (how structured audit data converts to avatar speech). Prototype with a mock audit trail to validate the conversational flow and test user comprehension.