# Common Issues Playbook

Quick reference for resolving frequently reported issues.

## Table of Contents

1. [Login & Authentication Issues](#login--authentication-issues)
2. [Content Playback Issues](#content-playback-issues)
3. [Subscription & Payment Issues](#subscription--payment-issues)
4. [App Performance Issues](#app-performance-issues)
5. [Sync & Data Issues](#sync--data-issues)
6. [AI Mentor Issues](#ai-mentor-issues)
7. [Metaverse Issues](#metaverse-issues)

---

## Login & Authentication Issues

### User Cannot Login

**Symptoms**: User receives "Invalid credentials" or "Login failed" error

**Diagnostic Questions**:

1. When did this start happening?
2. Are you using the correct email address?
3. Have you tried resetting your password?
4. Are you logging in via email, Google, or Apple?

**Resolution Steps**:

1. **Verify Account Exists**
   - Check admin panel: `Users > Search > [email]`
   - If no account found, guide user to sign up

2. **Password Reset**

   ```
   1. Click "Forgot Password" on login screen
   2. Enter registered email address
   3. Check inbox (and spam folder)
   4. Click reset link (valid for 24 hours)
   5. Create new password (8+ chars, 1 number, 1 special)
   ```

3. **Social Login Issues**
   - Verify email associated with social account
   - Check if multiple accounts exist with same email
   - Guide to "Link Accounts" in settings

4. **Account Locked**
   - Check for multiple failed attempts
   - If locked, unlock via admin panel
   - Consider security verification if suspicious

**Escalate If**: Account shows security flags, user claims account was
compromised

---

### Two-Factor Authentication Issues

**Symptoms**: User cannot receive or enter 2FA code

**Resolution Steps**:

1. **SMS Code Not Received**
   - Verify phone number is correct
   - Check if carrier blocking short codes
   - Offer to resend code (max 3 attempts/hour)
   - Suggest using authenticator app instead

2. **Authenticator App Issues**
   - Verify time sync on device (Settings > Date & Time > Automatic)
   - Check app is showing Lilith account
   - Guide through removing and re-adding account

3. **Lost Access to 2FA Device**
   - Verify identity through backup email
   - Ask for recovery codes (provided at 2FA setup)
   - If no recovery codes: escalate to Tier 2 for identity verification

**Escalate If**: User cannot verify identity, suspected account takeover

---

## Content Playback Issues

### Meditation/Audio Won't Play

**Symptoms**: User clicks play but nothing happens, or audio cuts out

**Diagnostic Questions**:

1. Which specific content are you trying to play?
2. Does this happen with all content or just specific items?
3. What device and app version are you using?
4. Is your device connected to the internet?

**Resolution Steps**:

1. **Basic Troubleshooting**

   ```
   1. Force close the app and reopen
   2. Check device volume and ringer settings
   3. Ensure Bluetooth is not connected to another device
   4. Check internet connection
   ```

2. **Clear Cache (Mobile)**
   - iOS: Settings > Lilith > Clear Cache
   - Android: Settings > Apps > Lilith > Storage > Clear Cache

3. **Offline Mode Issues**
   - Verify content is downloaded (cloud icon vs device icon)
   - Check available storage space
   - Re-download affected content

4. **Streaming Quality Issues**
   - Check internet speed (minimum 1 Mbps)
   - Try switching to lower quality (Settings > Streaming Quality)
   - Switch from WiFi to cellular or vice versa

**Escalate If**: Multiple users reporting same content failing, server-side
issue suspected

---

### Video Content Issues

**Symptoms**: Yoga videos buffer, freeze, or won't load

**Resolution Steps**:

1. **Reduce Quality**
   - Settings > Video Quality > Auto or 480p

2. **Check Connection**
   - Speed test: minimum 5 Mbps for HD
   - Try different WiFi network

3. **Device Compatibility**
   - Verify device meets minimum requirements
   - Update app to latest version
   - Update device OS

4. **Browser Issues (Web)**
   - Clear browser cache and cookies
   - Try incognito/private mode
   - Disable browser extensions
   - Try different browser (Chrome recommended)

**Escalate If**: Widespread video issues, CDN problems suspected

---

## Subscription & Payment Issues

### Subscription Not Active After Purchase

**Symptoms**: User paid but shows as free tier

**Resolution Steps**:

1. **Verify Payment**
   - Check payment status in admin panel
   - Look for transaction ID in Stripe dashboard
   - Check for failed payment attempts

2. **App Store Subscriptions**
   - iOS: Have user check Settings > Apple ID > Subscriptions
   - Android: Have user check Play Store > Menu > Subscriptions
   - Verify subscription shows active status

3. **Sync Issues**
   - Force refresh: Pull down on main screen
   - Sign out and back in
   - Check if subscription appears in web account

4. **Manual Activation**
   - If payment confirmed, activate manually via admin
   - Document reason for manual activation
   - Monitor for recurring issues

**Escalate If**: Payment taken but cannot locate transaction, refund needed

---

### Refund Requests

**Refund Policy**:

- 7-day money-back guarantee for new subscriptions
- Pro-rated refunds for annual plans within 30 days
- No refunds for consumed AI tokens

**Resolution Steps**:

1. **Verify Eligibility**
   - Check subscription start date
   - Check usage history
   - Review refund policy terms

2. **Process Refund (If Eligible)**
   - Direct purchases: Process via Stripe
   - App Store: Guide user to request from Apple
   - Play Store: Process via Google Play Console

3. **Retention Offer**
   - Before processing, offer alternatives:
     - Downgrade to lower tier
     - Pause subscription (up to 3 months)
     - One-time discount for continuation

4. **Document Everything**
   - Log refund reason
   - Note any retention offers made
   - Update user record

**Escalate If**: High-value customer, complex billing situation, potential fraud

---

## App Performance Issues

### App Crashes on Launch

**Resolution Steps**:

1. **Force Restart Device**
   - iOS: Volume up, volume down, hold power
   - Android: Hold power 10+ seconds

2. **Reinstall App**
   - Delete app completely
   - Restart device
   - Download fresh from app store
   - Sign in with existing account

3. **Check Device Compatibility**

   ```
   Minimum Requirements:
   - iOS 14.0 or later
   - Android 8.0 or later
   - 2GB RAM minimum
   - 500MB free storage
   ```

4. **Collect Crash Report**
   - iOS: Settings > Privacy > Analytics > Lilith
   - Android: Settings > Developer Options > Bug Report

**Escalate If**: Crash affects specific app version, multiple users impacted

---

### Slow Performance

**Resolution Steps**:

1. **Basic Optimization**
   - Close other apps
   - Clear app cache
   - Reduce background app refresh

2. **Storage Management**
   - Check device storage (need 500MB+ free)
   - Delete unused downloaded content
   - Move media to cloud

3. **Network Optimization**
   - Reset network settings
   - Try different network
   - Disable VPN if active

**Escalate If**: Performance issues after app update, server-side slowdown

---

## Sync & Data Issues

### Progress Not Syncing

**Symptoms**: Meditation streaks, course progress, or settings not syncing
across devices

**Resolution Steps**:

1. **Force Sync**
   - Settings > Account > Sync Now
   - Wait 30 seconds for completion

2. **Check Connection**
   - Verify internet connectivity
   - Check if sync icon shows error

3. **Account Verification**
   - Confirm same account on all devices
   - Check for multiple accounts with similar emails

4. **Reset Sync**
   - Sign out on all devices
   - Sign in first on primary device
   - Wait for sync to complete
   - Sign in on secondary devices

**Escalate If**: Data appears lost, database inconsistency suspected

---

### Lost Data/Streaks

**Resolution Steps**:

1. **Check Server Records**
   - Admin panel shows server-side data
   - Compare with user's reported history

2. **Recovery Options**
   - If server has data: Force sync from server
   - If local only: Cannot recover, document for engineering

3. **Goodwill Gesture**
   - If data truly lost, consider:
     - Manually restoring streak
     - Offering premium time extension
     - Providing store credit

**Escalate If**: Multiple users affected, indicates system issue

---

## AI Mentor Issues

### AI Not Responding

**Symptoms**: AI conversation stuck, no response generated

**Resolution Steps**:

1. **Basic Checks**
   - Verify internet connection
   - Check if AI service status is operational
   - Try refreshing conversation

2. **Clear Conversation**
   - Start new conversation
   - If stuck mid-conversation, may need backend intervention

3. **Rate Limiting**
   - Check if user exceeded daily limit
   - Free tier: 5 conversations/day
   - Premium: 20 conversations/day
   - Pro: Unlimited

4. **Token Budget**
   - Check remaining token allocation
   - Reset is daily at midnight UTC

**Escalate If**: AI service outage, inappropriate AI responses

---

### Inappropriate AI Response

**Immediate Actions**:

1. **Document the incident**
   - Screenshot or copy exact response
   - Note conversation ID and timestamp
   - Record user's prompt

2. **Apologize to user**
   - Use response template: AI-INAPPROPRIATE-001

3. **Report internally**
   - Post in #ai-safety channel immediately
   - Include all documentation

4. **Do NOT**
   - Dismiss user's concern
   - Attempt to explain/justify the response
   - Promise it won't happen again

**Escalate**: Always escalate to Tier 2 and AI Safety team

---

## Metaverse Issues

### Cannot Enter Virtual Space

**Resolution Steps**:

1. **Device Compatibility**

   ```
   Minimum for Metaverse:
   - WebGL 2.0 capable browser/device
   - 4GB RAM
   - Dedicated GPU recommended
   - Stable internet (10+ Mbps)
   ```

2. **Browser Setup (Web)**
   - Enable WebGL in browser settings
   - Disable hardware acceleration blocking
   - Allow Lilith to use microphone/camera

3. **Performance Mode**
   - Settings > Metaverse > Performance Mode
   - Reduces quality for better stability

**Escalate If**: Metaverse server issues, collision/physics bugs

---

## Quick Resolution Checklist

For any issue:

- [ ] Identify specific symptoms
- [ ] Verify user account and subscription status
- [ ] Check system status page for outages
- [ ] Attempt standard troubleshooting
- [ ] Document all steps taken
- [ ] Escalate if unresolved after standard steps
- [ ] Follow up within SLA timeframe

---

_Updated: January 2026_
