pomodoro

What this skill does

# Pomodoro Timer Skill

## Overview

A 25-minute timer for focused work sessions that saves every session to SQLite. Enables history tracking, productivity analytics, and pattern recognition over time.

**This is a System Skill** - it provides handles to operate a personal data system. As commands run and sessions accumulate, context builds and compounds. The system learns patterns and provides increasingly valuable insights through an OODA loop of observation, orientation, decision, and action.

## Mental Model: The OODA Loop

Operating this skill involves running a continuous cycle:

1. **Observe** → Check current status (`./pomodoro status`) and review history (`./pomodoro history`)
2. **Orient** → Analyze patterns in the data (`./pomodoro stats --period week`)
3. **Decide** → Determine optimal actions (e.g., "Morning sessions have 95% completion - schedule deep work then")
4. **Act** → Start sessions (`./pomodoro start`), provide recommendations, celebrate milestones

Each cycle builds on accumulated data, making insights more valuable over time.

## Dependencies

- Binary location: `~/.claude/skills/pomodoro/pomodoro`
- Database: Auto-created at `~/.claude/skills/pomodoro/pomodoro.db` on first run
- No external dependencies required

## Quick Decision Tree

```
User task → What kind of request?
   ├─ Start focused work → Check status first, then start session
   ├─ Check current timer → Use status command
   ├─ Review productivity → Use stats command (day/week/month/year)
   ├─ View past sessions → Use history command
   └─ Stop early → Use stop command
```

## Core Commands

**To see all available options**: Run `./pomodoro --help` or `./pomodoro <command> --help`

### Starting a Session

Begin a Pomodoro session:

```bash
# Traditional 25-minute Pomodoro
./pomodoro start --task "Refactor authentication module"

# Custom durations and cycles
./pomodoro start --task "Quick review" --work 5 --break 3 --cycles 2
./pomodoro start --task "Deep focus" --work 50 --break 10 --cycles 1

# Flash cards (rapid cycles)
./pomodoro start --task "Flash cards" --work 2 --break 1 --cycles 5
```

**Options:**
- `--work <minutes>` - Work duration (default: 25)
- `--break <minutes>` - Break duration (default: 5)
- `--cycles <count>` - Number of work+break rounds (default: 1)

**Behavior:**
- Only one session can run at a time
- Timer runs in foreground showing progress every minute
- Breaks start automatically after work sessions
- Next work session starts automatically after break (if cycles remaining)
- Each work session saved separately to database

**JSON output example:**
```bash
./pomodoro start --task "Write docs" --json
# Returns: {"status": "started", "task": "Write docs", "duration": 25, "started_at": "2025-10-22T14:30:00Z"}
```

### Checking Status

See if a timer is running:

```bash
./pomodoro status
./pomodoro status --json  # For programmatic use
```

**Output example:**
```
Active session: "Write documentation"
Started: 2:30 PM
Time remaining: 18 minutes
```

### Viewing History

Review past sessions:

```bash
./pomodoro history --days 7    # Last 7 days
./pomodoro history --days 30   # Last 30 days
./pomodoro history --json      # For programmatic use
```

**Output includes:**
- Task names
- Start and completion times
- Duration
- Completion status (completed vs. stopped early)

### Analyzing Productivity

Get insights from accumulated data:

```bash
./pomodoro stats --period day     # Today's stats
./pomodoro stats --period week    # This week
./pomodoro stats --period month   # This month
./pomodoro stats --period year    # This year
./pomodoro stats --json           # For programmatic use
```

**Statistics include:**
- Total and completed sessions
- Completion rate (% of sessions finished)
- Total focus time
- Most productive hours of day
- Task distribution (which tasks completed most often)

**JSON output example:**
```json
{
  "period": "week",
  "total_sessions": 23,
  "completed": 19,
  "completion_rate": 0.826,
  "focus_hours": 7.9,
  "productive_hours": [9, 10, 11],
  "top_tasks": ["Refactoring", "Documentation", "Code review"]
}
```

### Stopping Early

End the current session before completion:

```bash
./pomodoro stop
```

Use when interruptions occur or task completes early. Session marked as incomplete in database.

## Essential Workflows

### Starting Focused Work

To help a user start a Pomodoro session:

1. **Check for active session**: `./pomodoro status`
2. **If clear, start with appropriate options**:
   - Traditional: `./pomodoro start --task "Deep work on authentication"`
   - Custom: `./pomodoro start --task "Sprint planning" --work 15 --break 5 --cycles 3`
   - Flash cards: `./pomodoro start --task "Vocabulary review" --work 2 --break 1 --cycles 10`
3. **Confirm to user**: "25-minute Pomodoro started for [task name]. Timer running."

### Daily Review

To provide daily productivity summary:

1. **Fetch today's data**: `./pomodoro stats --period day --json`
2. **Parse and present insights**:
   - "Completed 6 Pomodoros today (3.0 hours of focus time)"
   - "5/6 sessions completed - 83% completion rate"
   - "Most work on: Refactoring, Documentation"
   - "Productive hours: 9-11 AM"

### Weekly Analysis

To provide weekly productivity review:

1. **Fetch week's data**: `./pomodoro stats --period week --json`
2. **Identify patterns**:
   - Compare to previous weeks if data available
   - Note peak productive hours
   - Identify which task types have highest completion rates
3. **Make recommendations**:
   - "Schedule deep work during your peak hours (9-11 AM)"
   - "Coding sessions have 90% completion vs 70% for meetings - consider task segmentation"

### Pattern Recognition Over Time

As sessions accumulate, provide increasingly valuable insights:

**After a few sessions (1-5):**
- "Completed 3 Pomodoros today"
- "Building momentum with focus sessions"

**After several days (5-20 sessions):**
- "7 completed out of 9 sessions - 78% completion rate"
- "Most productive between 9-11 AM"

**After a week (20-50 sessions):**
- "Strong week: 23 sessions with 85% completion"
- "Peak productivity: 9-11 AM (95% completion) vs 2-4 PM (65% completion)"
- "Consider scheduling deep work in morning hours"

**After a month (50+ sessions):**
- "Coding tasks: 90% completion rate"
- "Documentation tasks: 70% completion rate"
- "Consider shorter Pomodoros (15 min) for documentation work"

**After several months (100+ sessions):**
- "Completion rate improving: 72% → 85% over last 3 months"
- "Wednesday is most productive day (92% completion)"
- "Afternoon sessions improve when limited to 15 minutes"
- "80% more sessions completed on coding vs documentation tasks"

**Commands to use for pattern recognition:**
```bash
./pomodoro stats --period month --json  # Get monthly data
./pomodoro history --days 90 --json     # Review last 90 days
```

### Milestone Celebrations

Acknowledge progress at key milestones:

- **10 sessions**: "First 10 Pomodoros complete - building the habit!"
- **50 sessions**: "50 sessions milestone - over 20 hours of focused work!"
- **100 sessions**: "100 Pomodoros! That's 40+ hours of deep focus time."
- **High completion rates**: "95% completion this week - excellent focus!"

To check milestone status: `./pomodoro stats --period year --json`

## Common Pitfalls

### Starting When Session Already Active

❌ **Don't** start a new session without checking status first
✅ **Do** run `./pomodoro status` before starting

**Why**: Only one session can run at a time. Starting when active causes error.

**Pattern to follow**:
```bash
# Check first
./pomodoro status
# If "No active session", then start
./pomodoro start --task "New task"
```

### Non-Descriptive Task Names

❌ **Don't** use vague names: "Work", "Stuff", "Things"
✅ **Do** use specific names: "Refactor auth module", "Write API docs", "Review PR #123"

**Why**: Descriptive names enable better analytics. Pattern recognition needs specificity to identify which task types wor