# Autonomous V2 Debug Guide

Quick reference for debugging the Autonomous V2 decision system.

---

## 🔧 Enable Debug Mode

### Option 1: Environment Variable (Persistent)

Add to your `.env` file or `docker-compose.yml`:

```bash
AUTONOMOUS_DEBUG=true
```

### Option 2: Terminal (Temporary)

```bash
export AUTONOMOUS_DEBUG=true
python bot.py
```

### Option 3: Code (Development)

In `bot/globals.py`:
```python
AUTONOMOUS_DEBUG = True  # Force enable
```

---

## 📊 What You'll See

### Normal Mode (Debug Off)
```
🤖 [V2] Autonomous engine decided to: join_conversation for server 123456
✅ [V2] Autonomous tick queued for server 123456
```

### Debug Mode (Debug On)
```
🔍 [V2 Debug] Decision Check for Guild 123456
   Mood: bubbly (energy=0.90, sociability=0.95, impulsiveness=0.80)
   Momentum: 0.75
   Messages (5min/1hr): 15/42
   Messages since appearance: 8
   Time since last action: 450s
   Active activities: 2
   
   [Join Conv] momentum=0.75 > 0.63? True
   [Join Conv] messages=8 >= 5? True
   [Join Conv] cooldown=450s > 300s? True
   [Join Conv] impulsive roll? True | Result: True
   
✅ [V2 Debug] DECISION: join_conversation

🤖 [V2] Autonomous engine decided to: join_conversation for server 123456
✅ [V2] Autonomous tick queued for server 123456
```

---

## 🎯 Understanding the Output

### Decision Types Checked (in order)

1. **[Join Conv]** - High momentum conversation
   - Shows: momentum threshold, message count, cooldown, impulsiveness roll
   
2. **[Engage]** - User started new activity
   - Shows: active activities list, cooldown, sociability × impulsiveness threshold
   
3. **[FOMO]** - Lots of messages without Miku
   - Shows: message count vs threshold, momentum, cooldown
   
4. **[Silence]** - Break long silence
   - Shows: messages last hour, time threshold, energy roll
   
5. **[Share]** - Share tweet/content
   - Shows: quiet check, cooldown, energy threshold, mood appropriateness

### Context Signals

```
Mood: bubbly (energy=0.90, sociability=0.95, impulsiveness=0.80)
```
- Current mood and personality profile values

```
Momentum: 0.75
```
- Conversation momentum (0-1 scale)
- Higher = more active chat

```
Messages (5min/1hr): 15/42
```
- Recent activity levels
- First number: last 5 minutes
- Second number: last hour

```
Messages since appearance: 8
```
- How many messages since Miku last spoke
- Capped at 100 to prevent FOMO spam

```
Time since last action: 450s
```
- Seconds since Miku's last autonomous action
- Used for cooldown checks

```
Active activities: 2
```
- Number of user activities being tracked
- Max 5, auto-expire after 1 hour

---

## 🐛 Common Debugging Scenarios

### "Why isn't Miku joining the conversation?"

Enable debug mode and look for:
```
[Join Conv] momentum=0.45 > 0.63? False
```
- Momentum too low for current mood
- Try waiting for more messages or changing to more social mood

### "Why is Miku so chatty?"

Check the mood:
```
Mood: excited (energy=0.95, sociability=0.90, impulsiveness=0.90)
```
- High sociability = lower thresholds = more likely to act
- Change to "shy" or "serious" for less activity

### "Why isn't Miku reacting to user activities?"

Look for:
```
Active activities: 0
```
- No activities being tracked
- Check that presence intents are enabled
- Verify users are actually starting games/activities

### "Miku isn't breaking silence"

Check:
```
[Silence] msgs_last_hour=42 < 5? False
```
- Channel isn't quiet enough
- Energy roll might have failed (random)

### "No actions happening at all"

Check:
```
💤 [V2 Debug] Mood is 'asleep' - no action taken
```
- Miku is asleep! Change mood to wake her up

---

## 📈 Monitoring Tips

### Watch for Decay Task
Every 15 minutes you should see:
```
🧹 [V2] Decay task completed (iteration #4, uptime: 1.0h)
   └─ Processed 3 servers
```

If you don't see this, the decay task might not be running.

### Track Activity Events
When users do things:
```
👤 [V2] Username status changed: online → idle
🎮 [V2] Username started activity: Genshin Impact
```

If you never see these, presence tracking isn't working.

### Decision Frequency
In an active server, you should see decision checks:
- Every time a message is sent (but most will be "None")
- Every 10-15 minutes (scheduler tick)

---

## 🔍 Performance Impact

**Debug Mode OFF** (Production):
- Minimal overhead
- Only logs when actions are taken
- ~99% of checks are silent

**Debug Mode ON** (Development):
- Verbose logging on every decision check
- Can generate lots of output in active servers
- Useful for tuning but not for production

**Recommendation**: Only enable debug mode when actively troubleshooting.

---

## 🎛️ Tuning Thresholds

If you want to adjust behavior, edit `bot/utils/autonomous_engine.py`:

### Make Miku More Active
```python
# In _should_join_conversation
base_threshold = 0.5  # Lower from 0.6
```

### Make Miku Less Active
```python
# In _should_join_conversation
base_threshold = 0.7  # Raise from 0.6
```

### Change FOMO Sensitivity
```python
# In _should_respond_to_fomo
fomo_threshold = 30 * (2.0 - profile["sociability"])  # Raise from 25
```

### Adjust Silence Breaking
```python
# In _should_break_silence
min_silence = 2400 * (2.0 - profile["energy"])  # Raise from 1800 (30 min to 40 min)
```

**Note**: After tuning, monitor with debug mode to verify the changes work as expected.

---

## 📞 Quick Reference Commands

```bash
# Enable debug for current session
export AUTONOMOUS_DEBUG=true

# Disable debug
export AUTONOMOUS_DEBUG=false
unset AUTONOMOUS_DEBUG

# Check if debug is enabled
echo $AUTONOMOUS_DEBUG

# Watch logs in real-time
tail -f bot.log | grep "V2 Debug"

# Count decision checks in last hour
grep "Decision Check" bot.log | wc -l

# See all actions taken
grep "DECISION:" bot.log
```

---

## ✅ Troubleshooting Checklist

- [ ] Is `AUTONOMOUS_DEBUG=true` set?
- [ ] Did you restart the bot after setting the env var?
- [ ] Are presence intents enabled in `globals.py`?
- [ ] Is the bot actually receiving messages?
- [ ] Is the mood set to something other than "asleep"?
- [ ] Is the decay task running (check logs every 15 min)?
- [ ] Are there actually users in the server to track?

---

**Happy debugging! With debug mode enabled, you'll have full visibility into every decision the autonomous system makes.** 🔍✨