💡 Avatar Coaching Mode: Opt-In Over-the-Shoulder Learning During Real Workflows

[github-actions[bot]]

Summary

An optional mode where the avatar explains what the agent is doing at each step during real workflow execution — translating tool calls, MCP interactions, and decision logic into plain-language coaching. "Right now I'm reading through your project files to understand the codebase structure. This helps me tailor my suggestions to your specific setup." Off by default (respecting FR22's hidden-thinking principle), toggled per-session via voice ("explain what you're doing") or a single UI control. Bridges the 68%-interest to 14%-deployment gap by building understanding alongside outputs.

Market Signal

68% of small businesses use AI regularly but only 14% have deployed an AI agent in production — the gap is knowledge and confidence, not access or interest. "Progressive disclosure of AI reasoning" is a confirmed 2026 UX design trend (Parallel HQ, CleverIT Group, YUJ Designs). The Claude Agent SDK's Dreaming feature (shipped May 2026) shows Anthropic investing in agent self-improvement through session analysis — coaching mode is the user-facing complement where USERS improve their understanding through the same transparency principle. The voice assistant market ($11.2B by 2026) increasingly differentiates on trust-building, not just task completion.

User Signal

FR22 mandates hiding intermediate agent thinking — the correct default for non-technical users who want outcomes, not process. But the PRD's secondary persona (Marcus, developer) explicitly wants to understand what the agent does. No existing discussion covers opt-in step-by-step learning during live workflows — #245 (Guided Interactive Onboarding) is a one-time first session, #291 (Teach-by-Demonstration) is about recording user actions for replay, and #324 (Deliberation Mode) is structured thinking WITHOUT execution. The key unlock persona is Sarah-who-grew-curious: a user who's been using TalkTerm for weeks and now wants to understand how the magic works.

Technical Opportunity

The Claude Agent SDK message stream already emits typed messages for every tool call, result, and decision point. The IPC bridge (main/ipc/) already forwards these to the renderer. Coaching mode adds a translation layer that converts SDK message types to plain-language explanations — a prompt engineering task, not an architecture change. The avatar's existing TTS pipeline and CaptionBar component (UX-DR5) handle delivery. The StatusIndicator component (UX-DR6) can show a coaching badge when the mode is active. The ActivityFeed display mode (UX-DR13) can display coaching annotations alongside the existing agent action stream.

Assessment

Dimension	Score	Rationale
Feasibility	high	Leverages existing SDK message stream and IPC bridge; primary work is prompt engineering for tool call → explanation mapping
Impact	med	Addresses the interest-to-deployment gap; builds trust for the Marcus persona and the growing-curious Sarah persona
Urgency	med	Most valuable once the core workflow loop is established; can be added as a toggle without architectural disruption

Adversarial Review

Strongest objection: This directly contradicts the core product thesis (FR22: hide intermediate thinking). If users wanted to see what the agent does, they'd use a terminal. Adding transparency undermines TalkTerm's simplicity promise.

Rebuttal: FR22 is the correct DEFAULT — coaching mode is opt-in and off by default. The PRD explicitly targets two personas with different transparency needs. Sarah (non-technical) will never enable it initially. Marcus (technical) will use it to build confidence in the agent. And crucially, Sarah-who-grew-curious — a user who's been using TalkTerm for weeks and now wants to understand — is the unlock persona. Coaching mode bridges "I trust it because it works" to "I trust it because I understand it." The avatar relationship makes this natural: asking a colleague to explain their work process is a sign of growing trust, not a failure of simplicity.

Suggested Next Step

Define the SDK message type → plain-language translation map for the top 10 tool types (Bash, Read, Write, Edit, WebSearch, WebFetch, Glob, Grep, MCP tool calls, sub-agent delegation). Design the coaching toggle UX (voice command + StatusIndicator badge). Create a side-by-side prototype of a brainstorming workflow with coaching mode on vs. off.