claude-home/productivity/troubleshooting.md

title	description	type	domain	tags
Task Manager Troubleshooting	Troubleshooting guide for the ADHD task manager system covering PATH issues, dashboard display problems, task management bugs, data persistence, Python dependencies, and emergency recovery.	troubleshooting	productivity	task-manager adhd dashboard rich python troubleshooting

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:

   grep "task-manager" ~/.bashrc
   # Should show: export PATH="$HOME/.claude/tools/task-manager:$PATH"
   

2. Reload shell configuration:

   source ~/.bashrc
   # Or open new terminal window/tab
   

3. Test commands:

   which task
   which task-dashboard
   # Both should show: /home/cal/.claude/tools/task-manager/[command]
   

Temporary Workaround

Use full paths until shell reloaded:

~/.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:

   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:

   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:

   echo $LANG
   # Should show UTF-8 (e.g., en_US.UTF-8)
   

4. Test rich library:

   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:

task
# Shows all tasks with priority emojis

Fix task priority (workaround):

# 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:

   task
   # Should show different current task or empty
   

2. Check data file:

   cat ~/.claude/tools/task-manager/tasks.json | python3 -m json.tool
   # Look for tasks with status: "completed"
   

3. Force move to next:

   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:

task done  # Complete current task
# System checks snoozed tasks and loads if ready

Check snoozed tasks manually:

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:

   ls -la ~/.claude/tools/task-manager/tasks.json
   # Should be writable by user
   

2. Fix permissions:

   chmod 644 ~/.claude/tools/task-manager/tasks.json
   

3. Validate JSON format:

   python3 -m json.tool ~/.claude/tools/task-manager/tasks.json
   # Should show formatted JSON without errors
   

4. Check for corruption:

   # 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:

task dump "First task"
# Creates tasks.json automatically

Manual initialization (if needed):

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

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

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:

   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:

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:

   # 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:

   export TERM=xterm-256color
   task-dashboard
   

2. Try alternate terminal:

   # Instead of tmux, try dedicated terminal window
   

3. Check tmux/screen version - update if old

Emergency Recovery

Complete Reset

# 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

# If you have backup file
cp ~/.claude/tools/task-manager/tasks.json.backup \
   ~/.claude/tools/task-manager/tasks.json

# Verify restore
task

Reinstall System

# 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:

chmod +x ~/.claude/tools/task-manager/task*

Dashboard exits immediately

Cause: Python exception or Ctrl+C pressed Solution: Run with error output:

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:

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

Check Logs

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.