💡 Intelligent Failure Diagnostics: Avatar-Narrated Root Cause Analysis When Workflows Go Wrong

[github-actions[bot]]

Summary

When an agent workflow fails or produces poor results, the avatar goes beyond translating the error into plain language (FR34-35) by performing intelligent root cause analysis. The avatar distinguishes between agent-side issues (model limitations, tool failures, context overflow) and user-side issues (input format problems, missing data, insufficient permissions), explains its diagnostic reasoning conversationally, and proposes targeted fixes for each category: "I tried three approaches to analyze your spreadsheet, but each hit a formatting issue. The problem is that your file has merged cells in the header row. Want me to try a different approach, or should I walk you through fixing the headers first?"

Market Signal

Enterprise AI adoption data shows the biggest trust destroyer is unexplained failures — "the AI didn't work and I don't know why" (Symphony Solutions, Neontri). ChatGPT shows generic error messages. Siri says "I can't do that." No competitor performs intelligent failure diagnostics with root cause hypothesis generation and conversational explanation. Anthropic's Outcomes feature (May 2026) introduced rubric-based grading that can assess whether agent output meets quality criteria (Anthropic Blog) — this same reasoning capability can power diagnostic analysis of failures, turning a negative moment into a trust-building interaction.

User Signal

TalkTerm's PRD FR34-35 specifies conversational error communication with recovery options, but stops at error translation — the avatar reports what went wrong and offers 2-3 recovery options. There is no specification for why analysis. Discussion #416 (Confidence-Transparent Avatar) addresses uncertainty signaling during normal operation but not failure diagnosis. Discussion #433 (Agent Trust & Transparency Dashboard) covers proactive visibility, not reactive diagnostics. Non-technical users are the most likely to abandon a tool after an unexplained failure — intelligent diagnostics directly addresses the retention risk at TalkTerm's most vulnerable moment: when things go wrong.

Technical Opportunity

The audit trail (FR27-29) already captures the full sequence of agent actions, tool calls, and outcomes leading to any failure — this is the raw material for diagnostics. Claude's reasoning capability can generate diagnostic hypotheses by analyzing:

Input	Source	Diagnostic Value
Error type & message	SDK error event	Classify into known failure patterns
Tool call history	Audit trail (FR27-29)	Identify which step failed and what was attempted
Input characteristics	User-provided files/data	Detect format issues, missing data, size problems
Agent reasoning trace	SDK message stream	Understand what the agent was trying to do
Session context	Memory/history	Check if this failure pattern has occurred before

Failure Taxonomy

Category	Agent-Side Examples	User-Side Examples
Data	Context window overflow, token limit	File format issues, missing required fields, encoding
Tool	API timeout, rate limit, permission denied	Wrong file path, locked file, insufficient disk space
Model	Hallucination detected, instruction confusion	Ambiguous request, contradictory constraints
Environment	Network loss, service unavailable	Admin privileges missing, dependency not installed

The avatar state machine can add a "diagnosing" animation state (distinct from "thinking") to signal active investigation. Diagnostic results present via the existing ActionCard system with confidence-calibrated options.

Assessment

Dimension	Score	Rationale
Feasibility	high	Audit trail provides data; Claude reasoning generates hypotheses; existing UI presents results
Impact	high	Transforms the most trust-damaging moment (failure) into a trust-building interaction
Urgency	med	Important for retention once users encounter their first failures; not blocking initial adoption

Adversarial Review

Strongest objection: Incorrect diagnoses erode trust more than no diagnosis at all. If the avatar confidently misidentifies the root cause, users may spend time on the wrong fix and lose confidence in the tool permanently.

Rebuttal: Three safeguards prevent overconfident misdiagnosis: (1) Confidence-calibrated language — "I'm fairly confident the issue is..." vs "One possibility is..." based on diagnostic certainty, mapped to known error pattern matching, (2) Multiple hypotheses — always present 2-3 ranked possibilities rather than a single definitive diagnosis, giving the user agency to choose which to investigate, (3) Graceful uncertainty — include "I'm not sure what went wrong — let me try a completely fresh approach" as a standing option that acknowledges diagnostic limits. The diagnostic prompt explicitly instructs Claude to distinguish between high-confidence diagnoses (matching known error patterns with clear evidence) and speculative hypotheses. Even imperfect diagnostics are better than a generic "something went wrong" — the user learns something about their data, the tool's capabilities, and how to structure future requests.

Suggested Next Step

Define the failure taxonomy (agent-side vs user-side categories with common patterns per tool type in the Claude Agent SDK). Design the diagnostic prompt template that takes audit trail context as input and produces ranked root cause hypotheses with confidence levels. Prototype with 3-5 common failure scenarios from the BMAD brainstorming workflow: file format issues, context overflow, API rate limits, ambiguous user requests, and missing workspace permissions.