Feature Owner: Mich Tapawan → James Derick Billate
Module: Develop (Content Production)
Priority: Must
Date: July 8, 2026
Executive Summary
What is this feature?
The Mentor Persona feature allows Creators to select a “Companion” avatar that guides learners throughout their learning journey in WyzQuests. This feature enables the selection from three distinct persona types (Sage, Warrior, Healer) that serve as visual guides and enhance the learning experience through character-driven engagement.
Why does it matter?
Modern learning experiences benefit significantly from personalized guidance. By introducing mentor personas, it enhances engagement of learners, provides accommodating atmosphere, gamifies the experience and turns the learning environment into motivational rather than only sequential.
What's the MVP scope?
Selection of customizable or predefined personas
Player UI integration of selected avatar.
Saving and modifying of the avatar selected
1. User Pain Point & Solution
John is creating an interactive training program in WyzQuests but finds the interface feels impersonal and lacks visual elements that could increase learner engagement. He wants to add personality to his courses but has no way to customize the visual companion without manual design work.
Pain Points
Emotional: Frustrated, concerned and unsettled
Functional: No customization of quests, learners can’t form emotional connection, no visual hierarchy.
Business: More engagement will be gathers and increases course completion
2. 4D Framework Mapping
Diagnose: Provides another way to check content of accounts or users within specific permissions.
Design: Generates an overview of shared content.
Develop: Further enhances the workflow and organization of the team dynamics with its content
Deliver: Provides more way to deliver quality output by ensuring organized content per folder
3. USER FLOWS
Entry Points: Creator navigates to quest settings or content production area
Success Criteria: Creator successfully selects a persona, saves the choice, and the avatar appears in the Player UI when learners access the quest
Main Path (Happy Path)
Creator opens quest/course editing view
Creator navigates to “Mentor Persona” section
Creator views three persona options with visual previews
Creator clicks to select a persona (e.g., “Sage”)
Creator sees confirmation of selection
Creator saves quest changes
Persona avatar now appears in Player UI when learners view the quest
No Data: Display informational message if no persona is chosen; Default persona assigned (Sage) or prompt creator to select one
API Error: Display error message: “Unable to load personas. Please try again.” or termination of CRUD due to lack of data or incorrect one.
Permission Denied: Only Creators in that specific quest can modify personas
Decision Points:
IF persona selection submitted THEN validate and save ELSE show validation error
IF save successful THEN show success toast and update UI ELSE show error and retry
IF learner viewing quest THEN display selected persona avatar ELSE display default
4. Information Architecture
Primary Information
Quest/Course name
Available persona options (Sage, Warrior, Healer)
Persona descriptions and visual previews
Secondary Information
Currently selected persona indicator
Persona traits/descriptions
Preview of how avatar appears in Player UI
Tertiary Information
Persona recommendation based on course type (optional)
Actions
Primary CTA
"Select Persona" or direct persona selection
Secondary Actions
Preview persona in player
Change persona selection
Save selection
5. Data Requirements
Frontend Needs
Persona metadata (name, description, asset paths)
Quest/Course metadata
Current persona selection for display
Avatar asset URLs for rendering
API Calls Frontend Will Make
The overall CRUD of Mentor Persona avatar assignment to the quest
6. Performance Considerations
Database Optimization
Cache personas list in-memory or Redis (3 items, rarely change)
7. Security & Authorization
Who Can Access This Feature?
Administrator: No access.
Reviewer: No access.
Creator: Full access.
Learner: No access.
Agency Admin: No access.
8. Error Handling
Current Existing Error Handling
Invalid credentials → 401 Unauthorized
Expired session → 401 Unauthorized with redirect to login
Non-creator attempting to modify persona → 403 Forbidden
User attempting to modify another creator's quest → 403 Forbidden
Quest not found → 404 Not Found
Persona not found → 404 Not Found
Database connection failure → 500 Internal Server Error with retry prompt
Timeout on persona load → 504 Gateway Timeout with fallback to cached data
9. Testing Checklist
Happy Path
Creator navigates to quest editing view
Persona selection grid displays all three options (Sage, Warrior, Healer)
Creator selects a persona
Selection is confirmed with visual feedback (highlight, checkmark)
Creator saves quest
Persona data is persisted to database
Learner views quest and avatar appears correctly in Player UI
Avatar appears consistently across all learner interactions
Edge Cases
Non-creator cannot access persona selection (403 error)
Non-creator cannot modify persona (403 error)
Invalid persona_id returns appropriate error
Missing persona in database shows fallback/error state
API timeout handled gracefully with retry option
Concurrent persona selection requests handled correctly
10. OPEN QUESTIONS
Should persona selection influence lesson content or branching logic, or is it purely visual?
Should learners be able to override/switch personas during learning, or is it creator-locked?
Should persona data be included in SCORM exports for LMS compatibility?
11. OUT OF SCOPE
Voice/audio integration for personas (future phase)
Adaptive persona selection based on learner profile (future phase)
Persona progression or evolution during course (future phase)
Multi-language persona descriptions (current iteration)
12. SUCCESS METRICS
Persona being assigned to the quest
Persona displayed in the Quest Player in learner view
18. DEPENDENCIES
This feature depends on
Clerk Authentication
Quest Details API
Supabase Database
Asset Management
This feature depends on this
Player UI/Learner Interface
Quest Rendering Engine
19. TIMELINE & OWNERSHIP
Backend: Mich Tapawan
Frontend: Mich Tapawan
QA: Internal development testing
Estimated Completion: Feature completed.
Note: API Endpoints and Schema please refer to its Technical Documentation
