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:

   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.