💡 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.

[don-petry]

📋 Initiative planned by the BMAD Scrum Master (Bob).

Epic #333 — Guided Interactive Onboarding: avatar-led learn-by-doing first session

5 stories created (inert — labelled initiative, NOT initiative:auto):

• [Phase 1] Gated tutorial session type: first-launch detection, skip, and replay #334 (M) — [Phase 1] Gated tutorial session type: first-launch detection, skip, and replay
• [Phase 2] Scripted tutorial step engine driving avatar prompts and awaiting user interaction #335 (L) — [Phase 2] Scripted tutorial step engine driving avatar prompts and awaiting user interaction
• [Phase 3] The five tutorial steps producing a real persisted 3-item artifact #336 (L) — [Phase 3] The five tutorial steps producing a real persisted 3-item artifact
• [Phase 4] Role-adaptive tutorial content with a safe default #337 (M) — [Phase 4] Role-adaptive tutorial content with a safe default
• [Phase 4] Onboarding activation instrumentation and funnel report #338 (M) — [Phase 4] Onboarding activation instrumentation and funnel report

Open questions for review:

• Pipeline boundary: which tutorial steps (if any beyond the step-4 brainstorm) should run through the real agent pipeline vs. a scripted bypass? The discussion contradicts itself — Technical Opportunity says the tutorial IS a workflow through the same pipeline, while Suggested Next Step says it bypasses the full agent loop. The engine is built to let each step declare this, but the intended boundary needs a decision.
• What are the exact numeric targets for the success metrics (tutorial completion rate, activation lift, acceptable skip rate, time-to-first-artifact)? The metrics are defined and instrumented, but the pass/fail thresholds need product sign-off and were intentionally not baked into acceptance criteria.
• Where exactly is the user's role stored after setup (Epic 2), and what is the enumerated set of role values to map to content variants? Story 4 codes against a single accessor and a mapping table, but the source field and value set depend on Epic 2's implementation.
• Should users who skip the tutorial ever be re-prompted later (e.g., a one-time nudge), or is manual replay the only path back in? Current plan: skip is permanent for auto-launch and replay is manual-only.

---

Review the epic and its sub-issue DAG, adjust as needed, then add initiative:auto to epic #333 to hand it to initiative-driver for auto-implementation.