claude-home/productivity/troubleshooting.md

# Productivity Tools Troubleshooting Guide

## Task Manager Issues

### Problem: Commands not found
**Symptoms**: `task: command not found` or `task-dashboard: command not found`

**Root Cause**: PATH not configured or shell not reloaded

### Solution: PATH Configuration
1. **Verify PATH addition** in `~/.bashrc`:
   ```bash
   grep "task-manager" ~/.bashrc
   # Should show: export PATH="$HOME/.claude/tools/task-manager:$PATH"
   ```

2. **Reload shell configuration**:
   ```bash
   source ~/.bashrc
   # Or open new terminal window/tab
   ```

3. **Test commands**:
   ```bash
   which task
   which task-dashboard
   # Both should show: /home/cal/.claude/tools/task-manager/[command]
   ```

### Temporary Workaround
Use full paths until shell reloaded:
```bash
~/.claude/tools/task-manager/task
~/.claude/tools/task-manager/task-dashboard
```

## Dashboard Display Issues

### Problem: Dashboard not updating after CLI changes
**Symptoms**: Run `task dump "something"` but dashboard doesn't show new task

**Root Cause**: File system delay or dashboard not running

### Solution: Verify Dashboard Operation
1. **Check dashboard is running**:
   ```bash
   ps aux | grep dashboard.py
   ```

2. **Dashboard auto-refreshes every 1 second** - wait briefly

3. **If stuck, restart dashboard**:
   - Ctrl+C to stop
   - Restart: `task-dashboard`

4. **Verify data file exists**:
   ```bash
   ls -la ~/.claude/tools/task-manager/tasks.json
   cat ~/.claude/tools/task-manager/tasks.json
   ```

### Problem: Dashboard rendering issues (broken characters, layout problems)
**Symptoms**: Terminal shows garbled text, boxes not aligned

**Cause**: Terminal too small or doesn't support Unicode

### Solution: Terminal Requirements
1. **Minimum terminal size**: 80x24 characters
2. **Resize terminal window** to be larger
3. **Ensure Unicode support**:
   ```bash
   echo $LANG
   # Should show UTF-8 (e.g., en_US.UTF-8)
   ```

4. **Test rich library**:
   ```bash
   python3 -c "from rich.console import Console; Console().print('[green]✓[/green] Unicode works')"
   ```

## Task Management Issues

### Problem: High priority tasks not loading first
**Symptoms**: Low/medium priority task becomes current before high priority task

**Cause**: High priority task already loaded earlier or wrong priority flag used

### Solution: Priority System Understanding
**Priority Order** (automatic):
1. High priority tasks (🔴) - `--high` flag
2. Medium priority tasks (🟡) - `--medium` flag or default
3. Low priority tasks (🟢) - `--low` flag

**Check task priorities**:
```bash
task
# Shows all tasks with priority emojis
```

**Fix task priority** (workaround):
```bash
# Currently can't change priority - delete and re-add:
task next  # Skip past wrong-priority task
task dump "correct description" --high  # Re-add with right priority
```

### Problem: Task completed but still shows as current
**Symptoms**: After `task done`, same task still in current focus

**Cause**: Command failed or data file locked

### Solution: Verify Completion
1. **Check task status**:
   ```bash
   task
   # Should show different current task or empty
   ```

2. **Check data file**:
   ```bash
   cat ~/.claude/tools/task-manager/tasks.json | python3 -m json.tool
   # Look for tasks with status: "completed"
   ```

3. **Force move to next**:
   ```bash
   task next  # Skip to next task manually
   ```

### Problem: Snoozed task not waking up
**Symptoms**: Task snoozed hours ago but not appearing

**Cause**: Wake-up time not reached or system checks only on command execution

### Solution: Snooze Behavior
**How snooze works**:
- Task marked with future wake-up timestamp
- Next task auto-loaded immediately
- Snoozed task returns to queue when `snoozed_until` time passes
- **Only checked when commands run** (not automatic background wake)

**Trigger wake-up check**:
```bash
task done  # Complete current task
# System checks snoozed tasks and loads if ready
```

**Check snoozed tasks manually**:
```bash
cat ~/.claude/tools/task-manager/tasks.json | grep -A 5 '"status": "snoozed"'
```

## Data and Persistence Issues

### Problem: Tasks disappearing or data loss
**Symptoms**: Tasks added but gone after restart

**Cause**: File write permissions or corrupted JSON

### Solution: Data File Verification
1. **Check file permissions**:
   ```bash
   ls -la ~/.claude/tools/task-manager/tasks.json
   # Should be writable by user
   ```

2. **Fix permissions**:
   ```bash
   chmod 644 ~/.claude/tools/task-manager/tasks.json
   ```

3. **Validate JSON format**:
   ```bash
   python3 -m json.tool ~/.claude/tools/task-manager/tasks.json
   # Should show formatted JSON without errors
   ```

4. **Check for corruption**:
   ```bash
   # Backup current file
   cp ~/.claude/tools/task-manager/tasks.json ~/.claude/tools/task-manager/tasks.json.backup

   # Try to load with Python
   python3 -c "import json; json.load(open('$HOME/.claude/tools/task-manager/tasks.json'))"
   ```

### Problem: Data file doesn't exist
**Symptoms**: `task` command shows errors about missing file

**Cause**: First run or file accidentally deleted

### Solution: Initialize Data File
**Data file auto-creates on first use**:
```bash
task dump "First task"
# Creates tasks.json automatically
```

**Manual initialization** (if needed):
```bash
cat > ~/.claude/tools/task-manager/tasks.json << 'EOF'
{
  "tasks": [],
  "last_updated": "2025-01-01T00:00:00"
}
EOF
```

## Python Dependency Issues

### Problem: rich library not found
**Symptoms**: `ModuleNotFoundError: No module named 'rich'`

**Cause**: rich library not installed

### Solution: Install Dependencies
```bash
pip3 install --user rich
```

### Problem: Python version incompatibility
**Symptoms**: Syntax errors or import failures

**Cause**: Python version too old (requires 3.7+)

### Solution: Check Python Version
```bash
python3 --version
# Should be 3.7 or higher
```

If too old, use system Python 3 or install newer version

## Workflow and Usage Issues

### Problem: Forgetting to check dashboard
**Symptoms**: Dashboard running but never looking at it

**Cause**: Not visible enough, muscle memory not formed

### Solution: Visibility Improvements
1. **Use tmux/screen persistent split**:
   ```bash
   tmux split-window -h task-dashboard
   # Always visible in split pane
   ```

2. **Dedicated terminal on second monitor** - always visible

3. **Position terminal window** to always be on top/visible

4. **Build muscle memory**:
   - Use `task` command frequently to check status
   - Set reminders to check dashboard first 2 weeks
   - Terminal placement habit formation

### Problem: Still context switching instead of brain dumping
**Symptoms**: Remembering something and immediately switching tasks

**Cause**: Old habit pattern, not yet muscle memory

### Solution: Habit Building
**Interrupt pattern**:
1. Notice you're about to switch → STOP
2. Type: `task dump "[the thing]"`
3. See it appear in brain dump
4. Continue current work

**Muscle memory building**:
- Put note on monitor: "DUMP DON'T SWITCH"
- First week: Expect to fail, keep practicing
- Second week: Start catching yourself
- Third week: Becomes automatic

**Track progress**:
```bash
task
# Check completed today - celebrate wins!
```

## Performance Issues

### Problem: Dashboard slow or laggy
**Symptoms**: Dashboard updates slowly or terminal sluggish

**Cause**: Too many tasks in JSON file or terminal performance

### Solution: Data Cleanup
1. **Archive completed tasks**:
   ```bash
   # Manual cleanup (create archive script if needed)
   # Edit tasks.json to remove old completed tasks
   python3 -c "
   import json
   from datetime import datetime, timedelta

   with open('$HOME/.claude/tools/task-manager/tasks.json', 'r') as f:
       data = json.load(f)

   # Keep only last 7 days of completed tasks
   week_ago = (datetime.now() - timedelta(days=7)).isoformat()
   data['tasks'] = [
       t for t in data['tasks']
       if t['status'] != 'completed' or t.get('completed_at', '') > week_ago
   ]

   with open('$HOME/.claude/tools/task-manager/tasks.json', 'w') as f:
       json.dump(data, f, indent=2)
   "
   ```

2. **Check terminal performance**:
   - Try different terminal emulator
   - Reduce dashboard refresh rate (edit dashboard.py)

### Problem: Commands slow to execute
**Symptoms**: `task dump` takes several seconds

**Cause**: Large JSON file or slow file I/O

### Solution: Optimize Data Storage
- Keep tasks.json under 1000 tasks
- Archive old completed tasks monthly
- Consider SSD storage if on HDD

## Integration Issues

### Problem: Dashboard not visible in tmux/screen
**Symptoms**: Dashboard starts but can't see in multiplexer

**Cause**: Rich library rendering issues in some multiplexers

### Solution: Terminal Compatibility
1. **Set TERM variable**:
   ```bash
   export TERM=xterm-256color
   task-dashboard
   ```

2. **Try alternate terminal**:
   ```bash
   # Instead of tmux, try dedicated terminal window
   ```

3. **Check tmux/screen version** - update if old

## Emergency Recovery

### Complete Reset
```bash
# Stop dashboard
pkill -f dashboard.py

# Backup current data
mv ~/.claude/tools/task-manager/tasks.json \
   ~/.claude/tools/task-manager/tasks.json.backup

# Reinitialize
task dump "Test task"

# Verify working
task

# Restart dashboard
task-dashboard
```

### Restore from Backup
```bash
# If you have backup file
cp ~/.claude/tools/task-manager/tasks.json.backup \
   ~/.claude/tools/task-manager/tasks.json

# Verify restore
task
```

### Reinstall System
```bash
# Scripts already installed at:
# ~/.claude/tools/task-manager/

# Just reload PATH
source ~/.bashrc

# Initialize fresh data
task dump "Fresh start"
```

## Common Error Patterns

### "No module named 'task_manager'"
**Cause**: Running Python scripts directly from wrong directory
**Solution**: Use `task` and `task-dashboard` commands, not direct Python execution

### "Permission denied"
**Cause**: Scripts not executable
**Solution**:
```bash
chmod +x ~/.claude/tools/task-manager/task*
```

### Dashboard exits immediately
**Cause**: Python exception or Ctrl+C pressed
**Solution**: Run with error output:
```bash
python3 ~/.claude/tools/task-manager/dashboard.py
# See any error messages
```

## Prevention Best Practices

1. **Keep dashboard running** in persistent pane
2. **Use `task dump` immediately** when thoughts appear
3. **Trust the system** - don't manually organize JSON file
4. **Regular status checks** - `task` command throughout day
5. **Weekly review** - clean up stale tasks
6. **Back up data** - tasks.json to cloud storage
7. **Build muscle memory** - takes 2-3 weeks of consistent use

## Debug Mode

### Enable Detailed Logging
Add to Python scripts if troubleshooting needed:

```python
# In task_manager.py or cli.py
import logging
logging.basicConfig(level=logging.DEBUG,
                   filename='/tmp/task-manager-debug.log')
```

### Check Logs
```bash
tail -f /tmp/task-manager-debug.log
```

This troubleshooting guide addresses common issues with the ADHD task management system and provides recovery procedures for all known failure modes.