💡 Guided Interactive Onboarding: Avatar-Led Learn-by-Doing First Session

[github-actions[bot]]

Summary

Implement a structured 5-minute first-run experience where the avatar itself teaches the user how to interact with TalkTerm through a real mini-workflow. The avatar guides the user through voice input, text input, ActionCard selection, and output review — teaching by doing rather than by documentation. The tutorial adapts based on user's stated role and produces a real artifact so the experience feels productive, not pedagogical.

Market Signal

Duolingo's learn-by-doing onboarding is the gold standard for user activation in consumer apps. Notion, Figma, and Canva all use guided interactive tutorials for first-time users. In the AI agent space, Claude Cowork setup "takes under two minutes" (per Anthropic docs) but offers no guided capability discovery. Codex launched with two personality modes but no interactive tutorial. The 93.1% voice AI satisfaction rate (G2 2026 report) indicates users are ready for voice interaction — they just need the first push.

User Signal

TalkTerm's PRD Journey 1 describes Sarah's first 25-minute workflow, but the design assumes she already understands the interaction model (voice + avatar + overlay cards). The gap between setup completion (Epic 2) and first successful workflow (Epic 6) is where non-technical users are most likely to drop off. No existing idea (#55-#234) addresses structured first-use guidance. The combined input modes (voice, text, click, keyboard shortcuts for ActionCards) create a novel interaction paradigm that users have no existing mental model for.

Technical Opportunity

The tutorial is a structured prompt sequence using existing systems: avatar TTS, ActionCards (UX-DR2), OutputPanel (UX-DR4), and text input (UX-DR9). No new infrastructure needed — the tutorial IS a workflow, running through the same agent pipeline as any other session. Detection of first launch is trivial (check user profile existence per FR36). The tutorial produces a real micro-artifact (e.g., a 3-item brainstorm) so users leave with something tangible.

Assessment

Dimension	Score	Rationale
Feasibility	high	Uses existing avatar, ActionCard, and agent pipeline systems; tutorial is just a structured prompt sequence
Impact	high	Bridges the critical gap between setup and first workflow; directly targets the non-technical user adoption problem
Urgency	high	Must be designed alongside Epics 2-5 to ensure coherent first-use experience; retrofit is harder than built-in

Adversarial Review

Strongest objection: TalkTerm is supposed to be so intuitive it doesn't need a tutorial. Adding one admits the UX isn't good enough.

Rebuttal: Even the most intuitive products benefit from guided first-use when the interaction model is genuinely novel. Users have never talked to an animated avatar that executes real agent actions and presents results as overlay cards — there's no prior mental model to draw on. The tutorial isn't compensating for bad UX; it's establishing a new interaction paradigm. Power users skip it in 2 seconds (first-launch-only, with skip option). Non-technical users — TalkTerm's primary target — get the gentle introduction that converts them from curious installers to daily users.

Suggested Next Step

Design the 5-minute tutorial flow: (1) avatar introduces itself and explains the three interaction modes, (2) guided voice input exercise, (3) guided ActionCard selection, (4) mini-brainstorm producing a real 3-item artifact in the OutputPanel, (5) avatar summarizes what the user learned. Implement as a special session type that bypasses the full agent loop for the tutorial steps.