claude-home/productivity/CONTEXT.md

# Productivity Tools - Technology Context

## Overview
ADHD-optimized task management system designed to break the context-switching spiral. The system uses a persistent terminal dashboard with zero-friction brain dump capture to help maintain focus while capturing interrupting thoughts.

## Architecture Patterns

### Single-Focus with Brain Dump Pattern
**Pattern**: One visible task at a time with instant thought capture
- **Current Focus**: Single task display with time tracking
- **Brain Dump**: Zero-friction capture without context switching
- **Auto-Progression**: System-managed task transitions
- **Priority Queue**: Automatic high→medium→low ordering

**When to Use**:
- ADHD workflow challenges
- Frequent context switching problems
- "Meant to do" task accumulation
- Need for always-visible task tracking
- Terminal-based work environments

### Design Principles
1. **Minimal Friction**: Two-second task capture without switching
2. **Always Visible**: Persistent terminal dashboard prevents forgetting
3. **Single Focus**: One task display reduces overwhelm
4. **Auto-Progression**: System picks next task, reducing decision fatigue
5. **Time Awareness**: Duration tracking without judgment

## Core Components

### Task Manager Core
**Purpose**: Central task management with priority queuing and state management
**Location**: `~/.claude/tools/task-manager/task_manager.py`

**Key Features**:
- Priority-based task ordering (High/Medium/Low)
- Task states: brain_dump, current, completed, snoozed
- Auto-progression on task completion
- Snooze functionality with time-based wake-up
- JSON-based persistence

**Data Model**:
```python
class Task:
    id: str                      # Timestamp-based unique ID
    description: str             # Task description
    priority: str                # high, medium, low
    status: str                  # brain_dump, current, completed, snoozed
    created_at: str             # ISO timestamp
    started_at: Optional[str]   # When task became current
    completed_at: Optional[str] # Completion timestamp
    snoozed_until: Optional[str] # Wake-up time for snoozed tasks
```

### Terminal Dashboard
**Purpose**: Persistent visual display of current focus and brain dump queue
**Location**: `~/.claude/tools/task-manager/dashboard.py`

**Display Components**:
- Current focus with elapsed time
- Brain dump queue (up to 8 tasks visible)
- Completion statistics
- Command reference

**Update Behavior**:
- Auto-refreshes every 1 second
- Reads from JSON file (detects CLI changes)
- Uses rich library for clean TUI rendering

### CLI Interface
**Purpose**: Zero-friction command-line task operations
**Location**: `~/.claude/tools/task-manager/cli.py`

**Core Commands**:
- `task dump "description"` - Brain dump capture (most important!)
- `task done` - Complete current, auto-load next
- `task next` - Skip to next task
- `task snooze [hours]` - Snooze current task
- `task add "description" --now` - Add and make current
- `task` - Show current status

**Priority Flags**:
- `--high` - High priority (🔴)
- `--medium` - Medium priority (🟡) [default]
- `--low` - Low priority (🟢)

## Implementation Patterns

### The Context-Switch Spiral Solution
**Problem Pattern**:
```
Working on Task A → Remember Task B → Switch to Task B →
Remember Task C → Task A forgotten → Task B becomes "meant to do" → Loop
```

**Solution Pattern**:
```
Working on Task A → Remember Task B → `task dump "Task B"` →
Continue Task A → Complete with `task done` → System auto-loads Task B
```

### Brain Dump Workflow
1. **Capture**: `task dump "thought"` (2 seconds, no context switch)
2. **Visible**: Task appears in brain dump queue on dashboard
3. **Continue**: Keep working on current focus
4. **Auto-Load**: Task surfaces when current task completes

### Priority Management
**Automatic Ordering**:
1. High priority tasks (🔴) surface first
2. Medium priority tasks (🟡) second
3. Low priority tasks (🟢) last
4. Within priority level, oldest tasks first

**Use Cases**:
- `--high`: Urgent, time-sensitive, or blocking tasks
- `--medium`: Normal daily work (default)
- `--low`: "Nice to have", research, exploration

### Time Tracking Pattern
**Purpose**: Awareness without judgment
- Shows elapsed time on current task
- No alerts or pressure
- Helps identify time sinks naturally
- User decides when to move on

## Common Workflows

### Morning Startup
```bash
# Brain dump everything you need to do
task dump "Review PRs" --high
task dump "Update documentation"
task dump "Research new library" --low

# Load first task (highest priority)
task next

# Start dashboard in persistent pane
task-dashboard
```

### During Work Day
```bash
# Working on current task... suddenly remember something
task dump "email Staci about dinner"

# Thought is captured, visible in brain dump, keep working

# Finish current task
task done
# → Auto-loads next task from queue
```

### Handling Interruptions
```bash
# Urgent task comes up
task add "Fix production bug" --now --high
# → Immediately becomes current focus
# → Previous task moved back to brain dump

# Can't work on current task right now
task snooze 2
# → Snoozed for 2 hours
# → Next task auto-loaded
```

### End of Day
```bash
# Check what's left
task

# Everything in brain dump waits for tomorrow
# Completed tasks tracked in stats
```

## Best Practices

### Dashboard Setup
**Persistent Pane Strategy**:
- Use tmux/screen split pane for dashboard
- Keep visible on secondary monitor
- Always-visible = can't forget to check
- Alternative: Dedicated terminal window

**Terminal Multiplexer Example** (tmux):
```bash
# Split terminal horizontally
tmux split-window -h

# Run dashboard in right pane
task-dashboard

# Work in left pane
```

### Brain Dump Discipline
**Key Principles**:
- Capture thoughts immediately when they appear
- Don't evaluate or organize - just dump
- Trust the system to surface them later
- Priority can be added later if wrong

**Anti-Patterns to Avoid**:
- Stopping work to add detailed task information
- Trying to organize tasks while capturing
- Skipping capture because task seems "small"
- Context switching to "quickly do" the task

### Priority Usage
**High Priority** - Use sparingly:
- Urgent deadlines (today/this week)
- Blocking other people's work
- Production issues
- Time-sensitive opportunities

**Medium Priority** - Default for most work:
- Regular daily tasks
- Normal project work
- Scheduled activities

**Low Priority** - Background/optional:
- Research and exploration
- "Someday/maybe" items
- Nice-to-have improvements

### System Maintenance
**Daily**:
- Complete tasks as you work
- Brain dump new thoughts immediately
- Trust auto-progression

**Weekly**:
- Review low-priority items
- Clean up stale tasks
- Adjust priorities if needed

## Integration Patterns

### PATH Integration
**Location**: `~/.bashrc`
```bash
export PATH="$HOME/.claude/tools/task-manager:$PATH"
```

**Benefits**:
- `task` and `task-dashboard` available globally
- No full paths needed
- Muscle memory development

### Data Storage
**Location**: `~/.claude/tools/task-manager/tasks.json`
**Format**: JSON with task array and metadata

**Backup Strategy**:
- File-based storage enables easy backup
- Can sync via Dropbox/Google Drive if desired
- Simple JSON enables scripting/reporting

### Future Integration Points
**Planned Enhancements**:
- Notion MCP sync (Cal has integration available)
- Discord notifications on task completion
- Scheduled Jarvis check-ins (periodic reminders)
- Voice capture integration
- Pomodoro timer integration
- Analytics and reporting

## Technical Details

### File Structure
```
~/.claude/tools/task-manager/
├── task_manager.py      # Core task management logic
├── dashboard.py         # TUI dashboard (persistent display)
├── cli.py              # Command-line interface
├── task                # Shell wrapper for CLI
├── task-dashboard      # Shell wrapper for dashboard
├── tasks.json          # Data storage (auto-created)
└── README.md           # User documentation
```

### Dependencies
- Python 3.7+
- `rich` library for TUI rendering
- No other external dependencies

### Installation
**Already Installed** - Cal's system:
- Scripts: `~/.claude/tools/task-manager/`
- PATH: Added to `~/.bashrc`
- Data: `~/.claude/tools/task-manager/tasks.json`

## ADHD-Specific Optimizations

### Why Traditional Systems Fail
1. **Hidden in apps** - Out of sight, out of mind
2. **Too much organization** - Analysis paralysis
3. **Too many features** - Overwhelm and abandonment
4. **No immediate feedback** - Delayed dopamine
5. **Context switching required** - Defeats purpose

### How This System Addresses ADHD
1. **Always visible** - Persistent terminal display
2. **Minimal organization** - Just dump and go
3. **Minimal features** - Only what's needed
4. **Immediate feedback** - Instant completion confirmation
5. **Zero context switch** - Capture without abandoning work

### The Psychology
**Reduced Anxiety**: Thoughts are captured and visible
**Maintained Focus**: No need to switch away from current work
**Reduced Overwhelm**: Single focus display, not full list
**Dopamine Feedback**: Immediate confirmation on completion
**Decision Reduction**: System picks next task automatically

This productivity system is optimized specifically for ADHD workflows and terminal-based work environments, providing the minimal viable structure needed to maintain focus while capturing interrupting thoughts.