# Pomodoro Mate: Product Requirements Document

**Version:** 1.0
**Date:** April 2026
**Status:** Draft
**Author:** Product Team

---

## Executive Summary

Pomodoro Mate is an open-source, cross-platform Pomodoro timer that combines **authentic Pomodoro methodology** with **ADHD-aware design** and **outcome-oriented gamification**. It targets knowledge workers, students, and particularly users with focus challenges who are dissatisfied with basic timers that don't build lasting habits.

### The Problem

The Pomodoro timer market has 50+ apps, yet none adequately serve users who need:
1. **True Pomodoro methodology** — Most apps are just timers, ignoring Francesco Cirillo's five-phase process (planning, tracking, recording, processing, visualizing)
2. **ADHD-aware design** — No major tool is designed from the ground up for executive function challenges; traditional Pomodoro fails 60-70% of ADHD users within the first month
3. **Outcome-focused gamification** — Existing gamification (Forest, Habitica) rewards output (sessions completed) not outcomes (sustainable habits, personal growth)

### The Solution

Pomodoro Mate fills the white space at the intersection of:
- **Methodology-complete** Pomodoro implementation
- **ADHD-first** design philosophy
- **Outcome-oriented** gamification that builds identity, not just points
- **Privacy-first**, open-source, cross-platform architecture

### Target Launch

- **MVP (Phase 1):** 8 weeks — Web PWA with core timer, task selection, and basic gamification
- **Phase 2:** 12 weeks — macOS/iOS native apps with advanced features
- **Phase 3:** 16 weeks — Developer integrations (GitHub, Linear) and team features

---

## 1. Product Vision

### 1.1 Vision Statement

**For** knowledge workers and students with focus challenges (particularly those with ADHD traits), **who** are dissatisfied with basic timers that don't build lasting habits, **Pomodoro Mate** is the only open-source Pomodoro tool that combines true Pomodoro methodology with ADHD-aware design and outcome-oriented gamification — **helping you** become a more focused person, not just complete more sessions.

### 1.2 Core Differentiators

| Differentiator | Description | Why Competitors Can't Easily Copy |
|----------------|-------------|-----------------------------------|
| **Methodology-Complete** | Implements all six steps and five phases of Cirillo's technique | Requires deep integration between timer, tasks, analytics, and AI |
| **ADHD-First Design** | Every feature filtered through: "Does this reduce executive function burden?" | Requires rethinking every interaction from scratch |
| **Outcome Gamification** | Rewards sustainable habits and personal growth, not session counts | Requires measuring different metrics and designing different mechanics |
| **Open Source + Privacy** | Local-first, optional E2E sync, no tracking | Trust differentiator, community contributions |

### 1.3 Success Metrics

| Timeframe | Metric | Target |
|-----------|--------|--------|
| **6 months** | Active users | 1,000+ |
| **6 months** | Pro conversion | 5% |
| **12 months** | Active users | 5,000+ |
| **12 months** | GitHub stars | 500+ |
| **24 months** | Active users | 20,000+ |
| **24 months** | Revenue sustainability | Break-even |

---

## 2. Market Context

### 2.1 Market Landscape

The Pomodoro app market is **saturated but fragmented**:
- **500+ Pomodoro-related apps** across iOS, Android, web, and desktop
- **Productivity app market**: $98B+ by 2025
- **ADHD-focused app market**: $1.2B+ by 2028

### 2.2 Competitive Positioning

```
                    HIGH PRICE
                        │
         Session        │        Flow
         ($4.99/mo)     │        ($6.99/mo)
                        │
    ────────────────────┼────────────────────
                        │
         Forest         │        Pomodone
         ($3.99)        │        ($4.96/mo)
                        │
    ────────────────────┼────────────────────
                        │
    Pomofocus           │        Focus To-Do
    (Free)              │        (Free tier)
                        │
         Focus Keeper   │
         (Free)         │
                        │
                    LOW PRICE

    SIMPLE ─────────────────────────── FEATURE-RICH
```

**Pomodoro Mate Position:** Bottom-right quadrant (Free/Rich) initially, moving to Premium/Rich as Pro features launch.

### 2.3 Key Competitors

| App | Strengths | Weaknesses | Pomodoro Authenticity |
|-----|-----------|------------|----------------------|
| **Forest** | Gamification, 2M+ users | No task integration, juvenile feel | 6/10 |
| **Focus To-Do** | Cross-platform, task+timer | Feature bloat, dated UI | 4/10 |
| **Session** | Best analytics, macOS native | Apple-only, expensive | 5/10 |
| **Marinara** | Open source, simple | Browser-only, no mobile | 8/10 |
| **Super Productivity** | Developer integrations | Complex UI, recent backlash | 7/10 |
| **Flowkeeper** | Full methodology | Desktop-only, dated UI | 7/10 |

### 2.4 Market Gaps (Our Opportunities)

1. **No tool combines True Pomodoro + Modern Gamification + ADHD Support**
2. **No cross-platform privacy-first option**
3. **No tool enforces the original technique's interruption/voiding rules**
4. **No tool bridges the five phases digitally** (especially Processing phase)

---

## 3. User Personas

### 3.1 Primary Persona: The ADHD Professional

**Name:** Alex
**Demographics:** 28, software developer, diagnosed ADHD
**Goals:** Complete work without hyperfocus traps, build sustainable focus habits
**Pain Points:**
- Timer anxiety (countdown feels like a threat)
- Task initiation paralysis ("I can't start")
- Streak shame (one missed day ruins everything)
- Feature bloat overwhelming
- Tools designed for neurotypical brains

**How Pomodoro Mate Helps:**
- Flexible intervals that adapt to energy levels
- 1-tap quick start to overcome initiation paralysis
- Non-anxious visual timer (progress ring, not countdown)
- Streak freeze and fresh start mechanics
- Growth metaphors that never subtract

### 3.2 Secondary Persona: The Productivity Purist

**Name:** Jordan
**Demographics:** 35, product manager, Pomodoro practitioner for 5 years
**Goals:** Faithful technique implementation, better estimation skills
**Pain Points:**
- Apps allow too much customization (breaks the method)
- No interruption tracking
- No estimation vs. actual analysis
- Analytics are superficial

**How Pomodoro Mate Helps:**
- Purist Mode: Fixed 25/5/15 intervals with interruption voiding
- Estimation tracking per task
- AI-powered estimation correction
- Weekly technique adherence score

### 3.3 Tertiary Persona: The Privacy-Conscious Developer

**Name:** Sam
**Demographics:** 32, senior engineer, values open source
**Goals:** Local-first tool with GitHub integration
**Pain Points:**
- Most tools require cloud accounts
- No code-specific metrics
- Closed source = no trust

**How Pomodoro Mate Helps:**
- Local-first, optional E2E sync
- GitHub/Linear integration
- Open source, auditable
- Commit tracking per Pomodoro

---

## 4. Core Features

### 4.1 The Timer System

#### 4.1.1 Flexible Interval Engine

**P0 - MVP**

| Feature | Description | Default |
|---------|-------------|---------|
| Work intervals | User-configurable work duration | 25 min |
| Short breaks | Break after each work session | 5 min |
| Long breaks | Extended break after N sessions | 15 min |
| Long break trigger | Sessions before long break | 4 sessions |
| Auto-start breaks | Automatically start break timer | On |
| Auto-start work | Automatically start next work session | Off |

**P1 - Post-MVP**

| Feature | Description |
|---------|-------------|
| Energy-based suggestions | Morning check-in (1-5 scale) suggests interval length |
| Adaptive intervals | Learn from patterns, suggest optimal intervals |
| Flowtime mode | Work until focus drops (count-up instead of countdown) |
| Hyperfocus detection | Detect extended sessions, offer to continue |

#### 4.1.2 Timer Display

**P0 - MVP**

- **Visual progress ring** (fills clockwise, not countdown — reduces anxiety)
- **Current phase indicator** (Work / Short Break / Long Break)
- **Session counter** (2 of 4 sessions before long break)
- **Current task display** (what am I working on?)

**P1 - Post-MVP**

- **Non-anxious mode**: Hide time remaining, show only progress
- **Ambient sounds**: Rain, café, lo-fi, binaural beats (5+ options)
- **Focus music integration**: Spotify/Apple Music playlists

#### 4.1.3 Notifications

**P0 - MVP**

- Sound notification at session end
- System notification with action buttons
- Break reminder notification

**P1 - Post-MVP**

- Haptic feedback (mobile)
- Voice announcements (optional)
- Slack status auto-update

---

### 4.2 Task Management

#### 4.2.1 Task Selection (Planning Phase)

**P0 - MVP**

| Feature | Description |
|---------|-------------|
| Task list | Simple list of tasks for today |
| Task creation | Add task with title + optional notes |
| Pomodoro estimate | Estimate how many sessions needed |
| Task selection | Select which task to work on |
| Quick add | One-tap "just start" option (no task selection) |

**P1 - Post-MVP**

| Feature | Description |
|---------|-------------|
| Task decomposition | Break down large tasks into smaller steps |
| AI estimation | Suggest estimates based on historical data |
| Recurring tasks | Daily/weekly recurring tasks |
| Project grouping | Group tasks by project |

#### 4.2.2 Task Tracking (Tracking Phase)

**P0 - MVP**

- Track completed Pomodoros per task
- Visual indicator of progress vs. estimate
- Session notes (optional)

**P1 - Post-MVP**

- Interruption log (internal vs. external)
- Distraction capture pad
- Session quality rating (1-5 stars)

#### 4.2.3 Task History (Recording Phase)

**P0 - MVP**

- Daily archive of completed sessions
- Task completion log
- Basic export (CSV)

**P1 - Post-MVP**

- Structured daily review prompts
- Weekly summary generation
- Pattern analysis ("You focus best on Tuesday mornings")

---

### 4.3 ADHD-Specific Features

#### 4.3.1 Task Initiation Scaffolding

**P0 - MVP**

| Feature | Description |
|---------|-------------|
| Quick start | 1-tap timer start with no task selection |
| Micro-sessions | 5-minute "just start" option |
| First step prompt | "What's the tiniest first step?" |

**P1 - Post-MVP**

| Feature | Description |
|---------|-------------|
| Task decomposition helper | AI-powered "break this down" |
| Motivation priming | 10-second momentum builder |
| Body doubling mode | Virtual presence of others focusing |

#### 4.3.2 Failure-Spiral Prevention

**P0 - MVP**

| Feature | Description |
|---------|-------------|
| Daily fresh start | Every day is a new day, no carryover guilt |
| Streak freeze | One free pass per week |
| No penalty for voided sessions | Interruptions happen, that's okay |

**P1 - Post-MVP**

| Feature | Description |
|---------|-------------|
| Recovery mode | Gentle re-entry after time away |
| Self-compassion prompts | "You're not behind, you're here now" |
| Adjustable strictness | User controls how forgiving the system is |

#### 4.3.3 Hyperfocus Support

**P0 - MVP**

| Feature | Description |
|---------|-------------|
| Session extension | Easy "keep going" option |
| Break skip (with warning) | Allow skipping break, but log it |

**P1 - Post-MVP**

| Feature | Description |
|---------|-------------|
| Flow detection | Detect extended sessions, offer to continue |
| Flow protection | Suppress notifications during hyperfocus |
| Post-hyperfocus recovery | Suggest longer break after 2+ hour sessions |

#### 4.3.4 Executive Function Externalization

**P1 - Post-MVP**

| Feature | Description |
|---------|-------------|
| Distraction pad | Quick-capture intrusive thoughts |
| Auto task queue | Next task automatically suggested |
| Decision fatigue reduction | Limit visible choices to 3-5 |

---

### 4.4 Gamification System

#### 4.4.1 Philosophy: Outcome Over Output

**Core Principle:** Reward sustainable habits and identity formation, not session counts.

| Output Metrics (Avoid) | Outcome Metrics (Embrace) |
|------------------------|---------------------------|
| Sessions completed | Consistency rhythm development |
| Total hours focused | Focus quality improvement |
| Streak days | Recovery after breaks |
| Points accumulated | Identity evolution ("Deep Worker") |

#### 4.4.2 Growth Metaphor: The Garden

**P0 - MVP**

A personal garden that grows as you develop sustainable focus habits:

| Element | Description | Unlock |
|---------|-------------|--------|
| Garden plot | Personal visual space | Default |
| Plants | Grow with consistent sessions | Session completion |
| Garden expansion | More space for variety | Weekly consistency |
| Seasonal themes | Visual variety | Time-based |

**Key Design Principles:**
- **Growth only, never decay** — Plants don't die if you miss a day
- **Accumulation, not subtraction** — Everything you build persists
- **Ambient, not demanding** — Garden is background, not gameplay loop

#### 4.4.3 Identity-Based Progression

**P1 - Post-MVP**

| Level | Title | Unlocked By |
|-------|-------|-------------|
| 1 | Seedling | Complete onboarding |
| 2 | Sprout | 5 consistent days |
| 3 | Gardener | 2 weeks of practice |
| 4 | Cultivator | Demonstrate estimation accuracy |
| 5 | Deep Worker | 30 days of consistent practice |
| 6 | Focus Master | Maintain habits for 90 days |

**Key Principle:** These are identity labels, not XP levels. They reflect who you're becoming, not points accumulated.

#### 4.4.4 Self-Defined Reward Shop

**P1 - Post-MVP**

Users define their own rewards:

| Reward Type | Example |
|-------------|---------|
| Break activities | "15 min walk" |
| Entertainment | "Watch one episode" |
| Treats | "Get coffee" |
| Experiences | "Weekend trip after 30 days" |

**Mechanism:**
1. User defines rewards with "cost" in focus hours
2. System tracks progress toward rewards
3. User "redeems" when earned
4. No system-defined rewards (avoid generic badges)

#### 4.4.5 Social Features (Cooperative, Not Competitive)

**P2 - Future**

| Feature | Description |
|---------|-------------|
| Accountability partners | Paired progress sharing |
| Body doubling | Virtual presence during sessions |
| Team challenges | Cooperative (not competitive) goals |
| Focus rooms | Synchronized team Pomodoros |

**Anti-Patterns to Avoid:**
- No leaderboards
- No public comparison
- No competitive streaks
- No shame mechanics

---

### 4.5 Analytics & Insights (Processing + Visualizing Phases)

#### 4.5.1 Personal Dashboard

**P0 - MVP**

| Metric | Description |
|--------|-------------|
| Today's sessions | Sessions completed today |
| Today's focus time | Total minutes focused |
| Current streak | Consecutive days with at least one session |

**P1 - Post-MVP**

| Metric | Description |
|--------|-------------|
| Focus quality trend | Are sessions getting more focused? |
| Best focus times | When you focus best |
| Estimation accuracy | Predicted vs. actual Pomodoros |
| Break adherence | Are you taking proper breaks? |

#### 4.5.2 Weekly Insights

**P1 - Post-MVP**

AI-generated insights based on patterns:

| Insight Type | Example |
|--------------|---------|
| Pattern recognition | "You focus best on Tuesday mornings" |
| Estimation coaching | "You estimate 3 but typically need 5 for 'writing'" |
| Encouragement | "You've improved your consistency 20% this month" |
| Gentle suggestions | "Consider shorter sessions after lunch" |

#### 4.5.3 GitHub-Style Heatmap

**P0 - MVP**

- Visual contribution graph showing focus history
- Daily/weekly/monthly views
- Hover for session details

---

### 4.6 Developer Features

#### 4.6.1 GitHub Integration

**P2 - Future**

| Feature | Description |
|---------|-------------|
| Commit tracking | Associate commits with Pomodoro sessions |
| PR review mode | 25-minute review sessions |
| Issue time logging | Auto-log time to GitHub issues |

#### 4.6.2 Linear/Jira Integration

**P2 - Future**

| Feature | Description |
|---------|-------------|
| Task sync | Import tasks from project management |
| Time logging | Auto-log Pomodoros to tickets |
| Standup helper | Generate yesterday's work summary |

---

## 5. Technical Architecture

### 5.1 Platform Priority

| Priority | Platform | Rationale |
|----------|----------|-----------|
| 1 | **Web (PWA)** | Lowest friction, cross-platform, fast iteration |
| 2 | **macOS** | Highest willingness to pay, menu bar valued |
| 3 | **iOS** | Companion to macOS, widget support |
| 4 | **Windows** | Large market, lower price sensitivity |
| 5 | **Android** | Fragmented, lower monetization |

### 5.2 Tech Stack

**Recommended: Web-first PWA + Tauri for desktop**

| Component | Technology | Rationale |
|-----------|------------|-----------|
| Frontend | Next.js + React | Fast iteration, SSR/SSG options |
| Styling | Tailwind CSS | Rapid development, consistent design |
| PWA | next-pwa | Offline support, installable |
| Desktop | Tauri | Lightweight, native performance |
| State | Zustand | Simple, performant state management |
| Database (local) | SQLite (sql.js) | Full SQL, offline-first |
| Sync (optional) | ElectricSQL or PowerSync | CRDT-based sync |
| Auth (optional) | Clerk or Supabase Auth | User management |

### 5.3 Data Architecture

**Local-First Philosophy:**

```
┌─────────────────────────────────────────────┐
│                  Client                      │
├─────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────────────┐ │
│  │   SQLite    │───▶│  Optional E2E Sync  │ │
│  │  (Primary)  │    │   (User's Cloud)    │ │
│  └─────────────┘    └─────────────────────┘ │
└─────────────────────────────────────────────┘
```

**Data Ownership:**
- All data stored locally by default
- Optional encrypted sync (user provides cloud or our hosted option)
- Export to CSV/JSON anytime
- No vendor lock-in

### 5.4 Privacy & Security

| Principle | Implementation |
|-----------|----------------|
| Local-first | Core functionality works offline |
| No tracking | Zero analytics, telemetry, or tracking |
| Optional account | Full functionality without account |
| E2E encryption | All sync is end-to-end encrypted |
| Open source | Code is auditable |
| GDPR compliant | Data export, deletion on request |

---

## 6. User Experience

### 6.1 Design Principles

1. **Calm, not anxious** — Timer doesn't threaten, it supports
2. **Simple by default** — Core flow is 1-tap start
3. **Progressive disclosure** — Advanced features hidden until needed
4. **Forgiving, not punitive** — Missing a day is okay
5. **Beautiful, not distracting** — Design delights without demanding attention

### 6.2 Core User Flows

#### 6.2.1 Quick Start Flow (ADHD-Optimized)

```
Open App → Tap "Start" → Timer begins
```

No task selection, no configuration. Just start.

#### 6.2.2 Planned Session Flow

```
Open App → View Tasks → Select Task → Start Timer
```

#### 6.2.3 Task Estimation Flow

```
Add Task → Enter Title → Estimate Pomodoros → Save
```

Post-session: "You estimated 3, used 4. Update estimate?"

### 6.3 Visual Design

**Aesthetic:** Modern, calm, premium

| Element | Specification |
|---------|---------------|
| Primary color | Deep focus blue (#1a1a2e) |
| Accent | Growth green (#16a34a) |
| Typography | Geist or Inter |
| Border radius | 12px (soft, approachable) |
| Shadows | Subtle elevation, not dramatic |
| Animations | Smooth, optional (respect reduced motion) |

---

## 7. Pricing Model

### 7.1 Freemium Structure

| Tier | Price | Features |
|------|-------|----------|
| **Free** | $0 | Unlimited sessions, basic tasks, local storage, garden gamification |
| **Pro** | $3.99/month or $29.99/year | Cloud sync, advanced analytics, integrations, team features |
| **Lifetime** | $79.99 one-time | All Pro features forever |

### 7.2 What's Free vs. Paid

**Always Free:**
- Core timer (all interval options)
- Task list
- Session history
- Garden gamification
- All ADHD features
- Export data

**Pro Only:**
- Cross-device sync
- Advanced analytics (patterns, insights)
- GitHub/Linear integration
- Team features
- Priority support

**Rationale:** Core functionality is free. Monetize power users and teams, not basics.

---

## 8. Roadmap

### Phase 1: MVP (Weeks 1-8)

**Goal:** Core timer with task selection and basic gamification

| Week | Deliverables |
|------|--------------|
| 1-2 | Timer engine, visual display, system notifications |
| 3-4 | Task list, task selection, session tracking |
| 5-6 | Local storage, session history, CSV export |
| 7-8 | Garden gamification, heatmap, polish |

**Success Criteria:**
- Functional PWA installable on desktop/mobile
- Can complete a full Pomodoro session
- Tasks persist locally
- Basic gamification works

### Phase 2: Native Apps (Weeks 9-16)

**Goal:** macOS and iOS native apps with advanced features

| Week | Deliverables |
|------|--------------|
| 9-10 | macOS menu bar app (Tauri) |
| 11-12 | iOS app, widgets |
| 13-14 | Advanced analytics, weekly insights |
| 15-16 | Cloud sync (optional), Pro tier launch |

**Success Criteria:**
- Native macOS app in App Store
- Native iOS app in App Store
- Cross-device sync working
- 100+ paying Pro users

### Phase 3: Developer & Team (Weeks 17-24)

**Goal:** Developer integrations and team features

| Week | Deliverables |
|------|--------------|
| 17-18 | GitHub integration (commit tracking) |
| 19-20 | Linear/Jira integration |
| 21-22 | Team features (shared sessions, team stats) |
| 23-24 | Body doubling, accountability partners |

**Success Criteria:**
- 500+ GitHub stars
- 10+ teams using team features
- Break-even revenue

---

## 9. Success Metrics & KPIs

### 9.1 Product Metrics

| Metric | Target (6 mo) | Target (12 mo) |
|--------|---------------|----------------|
| Daily Active Users | 200 | 1,000 |
| Weekly Active Users | 500 | 3,000 |
| Sessions per user per day | 4+ | 4+ |
| 7-day retention | 30% | 40% |
| 30-day retention | 15% | 20% |

### 9.2 Business Metrics

| Metric | Target (6 mo) | Target (12 mo) |
|--------|---------------|----------------|
| Pro conversion rate | 3% | 5% |
| Monthly Recurring Revenue | $500 | $3,000 |
| Customer Acquisition Cost | < $5 | < $10 |
| Lifetime Value | > $40 | > $60 |

### 9.3 Quality Metrics

| Metric | Target |
|--------|--------|
| App Store rating | 4.5+ stars |
| NPS score | 40+ |
| Support response time | < 24 hours |
| Bug reports per month | < 10 |

---

## 10. Risks & Mitigation

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| **Market saturation** | High | Medium | Niche focus (ADHD, purists, developers) |
| **Feature copying** | High | Low | Speed, community, brand trust |
| **Monetization failure** | Medium | High | Freemium with clear value prop |
| **Platform dependency** | Medium | Medium | Web-first, avoid single platform lock-in |
| **Burnout (solo/small team)** | Medium | High | Open source community, phased launch |
| **Technique purism backlash** | Low | Low | Clear positioning, make flexibility optional |

---

## 11. Open Questions

| Question | Owner | Decision Date |
|----------|-------|---------------|
| Which sync provider to use? | Tech Lead | Week 10 |
| Native vs. Tauri for desktop? | Tech Lead | Week 8 |
| Pro pricing final amount? | Product | Week 12 |
| Which analytics provider (if any)? | Tech Lead | Week 6 |
| Garden vs. other growth metaphor? | Design | Week 4 |

---

## 12. Appendix

### 12.1 Glossary

| Term | Definition |
|------|------------|
| **Pomodoro** | A 25-minute focused work session |
| **Short break** | 5-minute break between sessions |
| **Long break** | 15-30 minute break after 4 sessions |
| **Purist Mode** | Strict Pomodoro with no customization |
| **Flowtime** | Flexible timing based on focus, not fixed intervals |
| **Garden** | The gamified growth metaphor |

### 12.2 Research Sources

1. Cirillo, F. (2007). The Pomodoro Technique (Version 1.3)
2. Market research reports (docs/market-research-*.md)
3. ADHD studies (docs/study-*.md)
4. Gamification research (docs/gamify-*.md)
5. Competitive analysis of 40+ apps
6. User interviews and feedback synthesis

### 12.3 Document History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | April 2026 | Product Team | Initial PRD |

---

**Document Status:** Ready for Review
**Next Step:** Stakeholder review and technical feasibility assessment