1630 lines
55 KiB
Markdown
1630 lines
55 KiB
Markdown
# Pomodoro-Mate: Product Requirements Document
|
|
|
|
> **Document Version:** 1.0
|
|
> **Date:** April 2026
|
|
> **Prepared By:** Product Management (Synthesized from AI Research Studies)
|
|
> **Status:** Draft for Stakeholder Review
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Executive Summary](#1-executive-summary)
|
|
2. [Problem Statement](#2-problem-statement)
|
|
3. [Target User Profile](#3-target-user-profile)
|
|
4. [Competitive Landscape](#4-competitive-landscape)
|
|
5. [Product Vision and Positioning](#5-product-vision-and-positioning)
|
|
6. [Core Feature Requirements](#6-core-feature-requirements)
|
|
7. [ADHD-Optimized Design Requirements](#7-adhd-optimized-design-requirements)
|
|
8. [Gamification Framework](#8-gamification-framework)
|
|
9. [User Journey](#9-user-journey)
|
|
10. [Technical Specifications](#10-technical-specifications)
|
|
11. [Non-Functional Requirements](#11-non-functional-requirements)
|
|
12. [Success Metrics and KPIs](#12-success-metrics-and-kpis)
|
|
13. [Launch Phases](#13-launch-phases)
|
|
14. [Ethical Considerations](#14-ethical-considerations)
|
|
15. [Open Questions](#15-open-questions)
|
|
|
|
---
|
|
|
|
## 1. Executive Summary
|
|
|
|
### 1.1 The Opportunity
|
|
|
|
The Pomodoro timer market is **saturated at the surface but underserved at depth**. While 500+ Pomodoro apps exist, none successfully combine:
|
|
|
|
1. **True Pomodoro Methodology** — Faithful implementation of Cirillo's five-phase system (Planning, Tracking, Recording, Processing, Visualizing)
|
|
2. **ADHD-Aware Design** — Features built from the ground up for executive function challenges, not adapted from neurotypical tools
|
|
3. **Outcome-Oriented Gamification** — Rewards sustainable habits and growth, not just session counts
|
|
4. **Cross-Platform Accessibility** — Accessible across web, mobile, and desktop with open-source foundation
|
|
|
|
**This gap represents a significant market opportunity.** The ADHD-focused app market is projected to reach $1.2B+ by 2028, and existing tools fail 60-70% of ADHD users within the first month.
|
|
|
|
### 1.2 Proposed Solution
|
|
|
|
**Pomodoro-Mate** is an ADHD-first Pomodoro tool that:
|
|
- Adapts the Pomodoro Technique to the neurobiology of ADHD rather than forcing ADHD users to adapt to a neurotypical tool
|
|
- Combines methodology-complete Pomodoro tracking with outcome-focused gamification
|
|
- Positions as the "first truly ADHD-aware Pomodoro tool" — not an afterthought adaptation but a purpose-built solution
|
|
- Builds an open-source community around ADHD productivity
|
|
|
|
### 1.3 Key Differentiators
|
|
|
|
| Differentiator | Description |
|
|
|----------------|-------------|
|
|
| **ADHD-First Architecture** | Every feature designed with ADHD cognitive profile as the primary constraint |
|
|
| **Methodology-Complete** | Full implementation of Cirillo's five phases, not just the timer |
|
|
| **Outcome Gamification** | Rewards growth, resilience, and sustainability over output metrics |
|
|
| **Forgiveness-First Design** | System designed to recover from failure, not punish it |
|
|
| **Open Source** | Community-driven, privacy-respecting, transparent |
|
|
|
|
### 1.4 Target Outcomes
|
|
|
|
- **3-4x higher retention** among ADHD users compared to existing Pomodoro tools
|
|
- **Measurable improvement** in focus self-efficacy within 30 days
|
|
- **Sustained engagement** beyond the typical 2-4 week novelty cliff
|
|
- **Positive user sentiment**: "Finally a tool that understands how my brain works"
|
|
|
|
---
|
|
|
|
## 2. Problem Statement
|
|
|
|
### 2.1 The ADHD Productivity Challenge
|
|
|
|
ADHD affects approximately **4-5% of adults globally** (10-12 million in the US alone), with significant functional impairment in occupational, academic, and personal domains. Time management difficulties rank among the **top three complaints** in adult ADHD clinical presentations.
|
|
|
|
**Core executive function deficits affecting productivity:**
|
|
- **Task initiation paralysis** — Knowing what to do but being unable to start
|
|
- **Time blindness** — Inability to accurately perceive, estimate, or track time
|
|
- **Attention dysregulation** — Binary attention (hyperfocus or disengagement) with poor middle states
|
|
- **Failure spirals** — One missed session triggers shame, avoidance, and abandonment
|
|
- **Dopamine reward pathway dysfunction** — Low-interest tasks feel physically aversive
|
|
|
|
### 2.2 Why Existing Tools Fail ADHD Users
|
|
|
|
| Neurotypical Assumption | ADHD Reality | Consequence |
|
|
|------------------------|--------------|-------------|
|
|
| Users can consistently self-regulate | Self-regulation fluctuates dramatically | Tools require too much executive function to use |
|
|
| Time is perceived linearly | Time perception is non-linear and inaccurate | Deadlines create pressure but not effective urgency |
|
|
| Motivation is relatively stable | Motivation is interest-dependent and variable | Reward structures don't provide adequate dopamine |
|
|
| Starting tasks is easy | Task initiation requires overcoming neurological inertia | Tools don't scaffold the transition |
|
|
| Breaks are naturally limited | Breaks become rabbit holes | Break mechanisms worsen productivity |
|
|
| Users process tasks linearly | Users oscillate between hyperfocus and disengagement | Linear workflows create friction |
|
|
|
|
### 2.3 Market Evidence of Failure
|
|
|
|
Research by Desrochers et al. (2019) found that adults with ADHD reported **significantly lower perceived effectiveness** of commonly used productivity tools compared to non-ADHD users, despite similar adoption rates. The disparity stems from **design misalignment**, not lack of use.
|
|
|
|
**The Failure Cascade:**
|
|
1. User downloads tool with enthusiasm
|
|
2. Initial novelty provides motivation (weeks 1-2)
|
|
3. ADHD novelty response wears off (weeks 3-4)
|
|
4. Rigid structure conflicts with variable capacity
|
|
5. Missed sessions trigger shame spiral
|
|
6. User abandons tool, internalizing failure as personal inadequacy
|
|
7. User believes "productivity tools don't work for me"
|
|
|
|
### 2.4 The Gamification Problem
|
|
|
|
Most gamified productivity apps use **output-focused gamification**:
|
|
- Points for tasks completed
|
|
- Streak counters that reset on miss
|
|
- Leaderboards that rank users
|
|
- Punitive mechanics (dead trees, avatar damage)
|
|
|
|
**These mechanics fail ADHD users specifically because:**
|
|
- Streak resets trigger the "what-the-hell effect" — one miss leads to abandonment
|
|
- Leaderboards create shame for lower performers
|
|
- Punitive mechanics increase anxiety, which impairs prefrontal cortex function
|
|
- Output metrics (quantity) ignore outcome quality (sustainability, growth)
|
|
|
|
### 2.5 The Methodological Gap
|
|
|
|
Francesco Cirillo's original Pomodoro Technique includes **five iterative phases** that most apps ignore:
|
|
|
|
| Phase | Purpose | Typical App Implementation |
|
|
|-------|---------|---------------------------|
|
|
| **Planning** | Select priorities, estimate Pomodoros per task | Basic task list (no estimation) |
|
|
| **Tracking** | Record effort during each Pomodoro | Session counter only |
|
|
| **Recording** | Archive completed Pomodoros daily | History view |
|
|
| **Processing** | Analyze where estimates matched reality | **No app does this well** |
|
|
| **Visualizing** | Use data to improve future planning | Basic charts |
|
|
|
|
**No existing tool digitally implements all five phases**, and the phases most neglected (Processing, Visualizing) are precisely the ones that ADHD users cannot perform manually due to executive function impairments.
|
|
|
|
---
|
|
|
|
## 3. Target User Profile
|
|
|
|
### 3.1 Primary Persona: "The Struggling Achiever"
|
|
|
|
**Name:** Maya
|
|
**Age:** 28
|
|
**Occupation:** Software Developer
|
|
**Background:** Diagnosed with ADHD (combined presentation) at age 24. Works at a tech startup with flexible remote policy.
|
|
|
|
**Goals:**
|
|
- Complete deep work sessions for challenging coding tasks
|
|
- Maintain consistent productivity without burning out
|
|
- Feel accomplished rather than ashamed at end of day
|
|
|
|
**Pain Points:**
|
|
- Task initiation paralysis — "I know what I need to do but I can't make myself start"
|
|
- Time blindness — loses hours to hyperfocus on low-priority tasks
|
|
- Shame spiral when tools "fail" — missed sessions feel like personal failures
|
|
- Overwhelm with complex projects — "where do I even begin?"
|
|
|
|
**Behaviors:**
|
|
- Has tried Forest, Focus To-Do, Habitica — abandoned each within 2-4 weeks
|
|
- Uses body doubling (Focusmate) occasionally with success
|
|
- Compensates with caffeine and deadline pressure
|
|
- Researches productivity tools frequently but has low trust in claims
|
|
|
|
**Quotations:**
|
|
- "Every tool I try makes me feel broken when I fail to use it consistently."
|
|
- "I need something that works with how my brain actually functions, not against it."
|
|
- "I've tried so many Pomodoro apps. They all feel the same."
|
|
|
|
**Jobs to Be Done:**
|
|
1. Start work sessions without the "wall of awful" blocking me
|
|
2. Track focus progress in a way that shows growth, not just activity
|
|
3. Recover gracefully from missed sessions without shame
|
|
4. Understand when and how I focus best (self-knowledge)
|
|
5. Maintain momentum over weeks and months, not just days
|
|
|
|
### 3.2 Secondary Persona: "The Anxious Optimizer"
|
|
|
|
**Name:** David
|
|
**Age:** 35
|
|
**Occupation:** Marketing Manager
|
|
**Background:** Self-suspects ADHD but not formally diagnosed. Has high-functioning anxiety alongside attention challenges.
|
|
|
|
**Goals:**
|
|
- Build sustainable focus habits
|
|
- Reduce anxiety around productivity metrics
|
|
- Feel in control of time rather than controlled by it
|
|
|
|
**Pain Points:**
|
|
- Timer anxiety — countdown creates pressure that impairs focus
|
|
- Perfectionism — one missed day ruins the whole system
|
|
- Over-optimization — spends more time configuring tools than using them
|
|
|
|
**Behaviors:**
|
|
- Sets up elaborate systems that he abandons within weeks
|
|
- Uses multiple overlapping productivity tools
|
|
- Reads extensively about productivity but struggles to implement
|
|
|
|
### 3.3 Tertiary Persona: "The Late-Diagnosed Professional"
|
|
|
|
**Name:** Sarah
|
|
**Age:** 42
|
|
**Occupation:** Attorney
|
|
**Background:** Recently diagnosed with ADHD (inattentive presentation). Spent decades developing coping mechanisms. Looking for tools that complement, not replace, existing strategies.
|
|
|
|
**Goals:**
|
|
- Integrate focus techniques into demanding legal work
|
|
- Reduce reliance on crisis-driven productivity
|
|
- Build sustainable practices for long-term career sustainability
|
|
|
|
**Pain Points:**
|
|
- Skepticism of "magic bullet" productivity claims
|
|
- Need for professional-grade tool (not juvenile gamification)
|
|
- Privacy concerns about data handling
|
|
|
|
### 3.4 User Segment Priorities
|
|
|
|
| Segment | Size Estimate | Priority | Specific Needs |
|
|
|---------|--------------|----------|----------------|
|
|
| Adults with diagnosed ADHD | ~4-5% of adults | **Primary** | Full ADHD-aware feature set |
|
|
| ADHD-suspecting but undiagnosed | Unknown (likely 2-3x diagnosed) | **Primary** | Flexible, forgiving design |
|
|
| High-functioning anxiety + attention challenges | Significant overlap | Secondary | Timer anxiety mitigation, low-pressure design |
|
|
| Productivity enthusiasts seeking optimization | Large market | Secondary | Outcome metrics, growth tracking |
|
|
|
|
---
|
|
|
|
## 4. Competitive Landscape
|
|
|
|
### 4.1 Competitive Positioning Map
|
|
|
|
```
|
|
HIGH PRICE
|
|
│
|
|
Session │ Flow
|
|
($4.99/mo) │ ($6.99/mo)
|
|
(macOS) │ (macOS)
|
|
│
|
|
────────────────────┼────────────────────
|
|
│
|
|
Forest │ Focus To-Do
|
|
($3.99) │ (Free tier)
|
|
(Gamification) │ (All-in-one)
|
|
│
|
|
────────────────────┼────────────────────
|
|
│
|
|
Pomofocus │ Super Productivity
|
|
(Free web) │ (Free, open source)
|
|
│
|
|
Focus Keeper │
|
|
(Free) │
|
|
│
|
|
LOW PRICE
|
|
|
|
SIMPLE ─────────────────────────── FEATURE-RICH
|
|
```
|
|
|
|
**Quadrant Analysis:**
|
|
- **Top-Left (Premium Simple):** Session, Flow — Apple users willing to pay for design
|
|
- **Top-Right (Premium Rich):** Focus To-Do — Best value for feature-seekers
|
|
- **Bottom-Left (Free Simple):** Pomofocus, Focus Keeper — Students, casual users
|
|
- **Bottom-Right (Free Rich):** Super Productivity — Power users, developers
|
|
|
|
### 4.2 Competitor Analysis
|
|
|
|
| Competitor | Strengths | Weaknesses | Pomodoro-Mate Advantage |
|
|
|------------|-----------|-----------|------------------------|
|
|
| **Forest** | Beautiful gamification, real-world impact (trees), strong brand | Rigid intervals, tree-death punishment, no true methodology, Apple/Android only | Forgiveness-first gamification, full methodology, cross-platform |
|
|
| **Focus To-Do** | Full task management, cross-platform, freemium model | Bloat, dated UI, low Pomodoro fidelity, no ADHD-awareness | ADHD-first design, methodology-complete, modern UI |
|
|
| **Super Productivity** | Open source, GitHub/Jira integration, powerful features | Complex interface, 2025 redesign broke workflows, no gamification | Gamified experience, ADHD-aware, simplified onboarding |
|
|
| **Session** | Beautiful Mac design, deep analytics | Apple-only, $4.99/mo, no gamification | Cross-platform, gamified, ADHD-aware |
|
|
| **Habitica** | Full RPG gamification, strong community | Zero Pomodoro methodology, overwhelming complexity, punishment mechanics | Pomodoro methodology + focused gamification |
|
|
| **Flowkeeper** | Only methodology-complete tool | Dated Java desktop-only UI, no gamification, abandoned development | Modern web-first design, gamified, ADHD-aware |
|
|
| **Goodtime** | Clean mobile-only design, open source | Mobile-only, limited features, no gamification | Cross-platform, gamified, full feature set |
|
|
|
|
### 4.3 Market Gaps Analysis
|
|
|
|
| Gap | Evidence | Opportunity |
|
|
|-----|---------|-------------|
|
|
| **ADHD-First Design** | No app designed from ground up for ADHD; Forest's "dead tree" actually harms ADHD users | Purpose-built ADHD-aware features |
|
|
| **True Pomodoro Methodology** | Flowkeeper is only methodology-complete tool; dated, desktop-only | Web-first, modern implementation of all 5 phases |
|
|
| **Outcome Gamification** | Forest/Habitica use output-focused mechanics; Way of Life (no streaks) is habit-only | Gamification that rewards growth, resilience, sustainability |
|
|
| **Cross-Platform Open Source** | Goodtime (mobile-only), Flowkeeper (desktop-only), both lack gamification | Web-first + native apps, open source, community-driven |
|
|
| **Processing & Visualizing** | All apps skip these phases | AI-powered pattern analysis, automated insights |
|
|
| **Failure Forgiveness** | Every app uses binary streak reset | Forgiveness-first architecture, momentum not streaks |
|
|
|
|
### 4.4 Competitive Threats
|
|
|
|
| Threat | Likelihood | Mitigation |
|
|
|--------|------------|------------|
|
|
| Forest adds ADHD-aware features | Medium | First-mover advantage; community building |
|
|
| Super Productivity redesign fixes UX | Medium | Differentiate on ADHD-focus, not just features |
|
|
| New entrant targets same gap | Medium-High | Speed to market; open source community moat |
|
|
| Forest/Habitica acquire smaller tools | Low-Medium | Open source community; no exit incentive |
|
|
|
|
---
|
|
|
|
## 5. Product Vision and Positioning
|
|
|
|
### 5.1 Vision Statement
|
|
|
|
**Pomodoro-Mate is the first productivity tool designed around how the ADHD brain actually works — not how we wish it worked.**
|
|
|
|
We believe that:
|
|
- Productivity tools should adapt to users, not force users to adapt to tools
|
|
- Failure should be a data point, not a death sentence
|
|
- Growth matters more than perfection
|
|
- The Pomodoro Technique, properly adapted, is uniquely powerful for ADHD — but only when properly adapted
|
|
|
|
### 5.2 Mission Statement
|
|
|
|
**Help individuals with ADHD build sustainable focus practices that honor their neurobiology, not fight it.**
|
|
|
|
We measure success not by sessions completed but by:
|
|
- Users who return after gaps
|
|
- Self-efficacy improvements
|
|
- Reduced shame around productivity
|
|
- Long-term engagement (90+ days)
|
|
|
|
### 5.3 Positioning Statement
|
|
|
|
**For** adults with ADHD (diagnosed or suspected) **who** struggle with focus, time management, and task completion, **Pomodoro-Mate** is the **productivity tool** that **actually understands how your brain works** — unlike generic Pomodoro timers that assume neurotypical executive function. **Unlike** Forest (which punishes you for leaving the app), Focus To-Do (which overwhelms with features), and Habitica (which gamifies everything except the methodology), **Pomodoro-Mate** is the **only tool that combines true Pomodoro methodology with ADHD-aware design and forgiveness-first gamification** — **so you can** build lasting focus habits without the shame spiral.
|
|
|
|
### 5.4 Brand Personality
|
|
|
|
| Attribute | Do | Don't |
|
|
|-----------|-----|-------|
|
|
| **Supportive** | Warm, encouraging, validating | Condescending, prescriptive, guilt-inducing |
|
|
| **Honest** | Acknowledge difficulty, don't minimize struggles | Promise magic results, oversimplify ADHD |
|
|
| **Flexible** | Adapt to user needs, offer choices | Impose rigid rules, punish deviation |
|
|
| **Growth-Oriented** | Celebrate progress, emphasize trajectory | Focus on perfection, shame gaps |
|
|
| **Respectful** | Trust user judgment, offer suggestions | Lecture, moralize, or shame |
|
|
| **Professional** | Serious about ADHD, evidence-informed | Juvenile (despite gamification), anti-clinical |
|
|
|
|
### 5.5 Naming Rationale
|
|
|
|
**Pomodoro-Mate** communicates:
|
|
- "Pomodoro" — The core technique (known brand in productivity space)
|
|
- "-Mate" — Companion, supporter, ally (not taskmaster)
|
|
- Warmth and approachability
|
|
- Partnership in the journey
|
|
|
|
---
|
|
|
|
## 6. Core Feature Requirements
|
|
|
|
### 6.1 Feature Priority Matrix
|
|
|
|
| Priority | Feature | User Need Addressed | Complexity |
|
|
|----------|---------|---------------------|------------|
|
|
| **P0** | Flexible interval timer (5-90 min) | ADHD attention variability | Low |
|
|
| **P0** | Task selection with Pomodoro estimation | Planning phase of methodology | Medium |
|
|
| **P0** | Automatic session tracking | Tracking + Recording phases | Low |
|
|
| **P0** | ADHD-aware quick start (1-tap, micro-sessions) | Task initiation paralysis | Low |
|
|
| **P0** | Visual timer (progress ring, color gradient) | Time blindness + timer anxiety | Low |
|
|
| **P0** | Growth visualization (garden/landscape) | Outcome gamification foundation | Medium |
|
|
| **P0** | Fresh start daily + momentum tracking | Failure spiral prevention | Medium |
|
|
| **P1** | Distraction capture pad | Distraction management | Low |
|
|
| **P1** | Session quality indicator | Outcome over output | Medium |
|
|
| **P1** | Weekly AI insights ("You focus best on Tuesdays") | Processing + Visualizing phases | High |
|
|
| **P1** | Hyperfocus-aware mode | Preserve productive flow states | Medium |
|
|
| **P1** | Energy/mood check-in | Adaptive interval suggestions | Low |
|
|
| **P1** | Self-defined reward shop | Outcome gamification | Medium |
|
|
| **P2** | Body doubling presence | Social scaffolding | High |
|
|
| **P2** | Task decomposition helper | Task initiation paralysis | Medium |
|
|
| **P2** | Accountability partnerships | Social accountability | High |
|
|
| **P2** | Break activity menu | Break derailment prevention | Low |
|
|
| **P3** | Team focus rooms | Social accountability | Very High |
|
|
| **P3** | GitHub/Jira integration | Developer workflow | High |
|
|
| **P3** | Wearable integration | Biometric-adaptive intervals | High |
|
|
|
|
### 6.2 P0 Features: Detailed Specifications
|
|
|
|
#### 6.2.1 Flexible Interval Timer
|
|
|
|
**Core Behavior:**
|
|
- Default intervals: 5, 10, 15, 25, 30, 45, 60, 90 minutes
|
|
- Default break intervals: 3, 5, 10, 15, 20 minutes
|
|
- Long break (after 4 sessions): 15, 20, 30 minutes (configurable)
|
|
- Users can save custom presets
|
|
- Per-task interval selection (system remembers preferences)
|
|
|
|
**Interval Recommendations:**
|
|
- Based on energy check-in: Low energy → shorter intervals suggested
|
|
- Based on historical data: "You complete 87% of 15-minute sessions"
|
|
- Based on task type: Routine tasks → shorter; Creative tasks → longer
|
|
|
|
**Timer Display Options:**
|
|
- Progress ring (fills clockwise) — primary recommendation for ADHD
|
|
- Color gradient (cool to warm)
|
|
- Digital countdown with optional seconds
|
|
- Nature metaphor (plant growth, water filling)
|
|
- Hide timer option (just alerts)
|
|
|
|
**Timer Sounds:**
|
|
- Gentle chime (default)
|
|
- Soft tone
|
|
- Nature sounds (rain, waves)
|
|
- Custom audio upload
|
|
- Vibration only (mobile)
|
|
- No sound option
|
|
|
|
#### 6.2.2 Task Selection with Pomodoro Estimation
|
|
|
|
**Task Input:**
|
|
- Quick-add task (one-line input)
|
|
- Full task creation (title, notes, estimated Pomodoros, resistance level)
|
|
- Task templates (recurring task patterns)
|
|
- Import from other tools (future: Notion, Todoist)
|
|
|
|
**Pomodoro Estimation:**
|
|
- Initial estimate prompt: "How many Pomodoros do you think this will take?"
|
|
- Track actual vs. estimated
|
|
- AI suggestion: "Based on similar tasks, estimate 3 Pomodoros"
|
|
- Adjustment prompt after each session
|
|
|
|
**Resistance Tagging:**
|
|
- Optional: Low / Medium / High resistance rating
|
|
- Affects interval recommendations
|
|
- High resistance → suggest micro-session
|
|
|
|
**Task Queue:**
|
|
- Ordered list of selected tasks
|
|
- Drag-and-drop reordering
|
|
- Auto-advance to next task on session complete
|
|
- "What's next?" prompt if queue is empty
|
|
|
|
#### 6.2.3 Automatic Session Tracking
|
|
|
|
**Session Data Captured:**
|
|
- Start time, end time, duration
|
|
- Task associated (if any)
|
|
- Interval length
|
|
- Completion status (completed, abandoned, extended)
|
|
- Session quality rating (post-session prompt)
|
|
- Distractions captured (count and notes)
|
|
- Energy level (pre-session check-in)
|
|
- Mood (pre-session check-in)
|
|
|
|
**Recording (Daily Archive):**
|
|
- Automatic daily summary at end of day
|
|
- Sessions grouped by day
|
|
- Weekly archive view
|
|
- Monthly archive view
|
|
- Data export (CSV, JSON)
|
|
|
|
**Tracking Display:**
|
|
- Today's progress (visual)
|
|
- This week's progress (bar chart)
|
|
- This month's progress (calendar heatmap)
|
|
- All-time totals (sessions, hours, tasks)
|
|
|
|
#### 6.2.4 ADHD-Aware Quick Start
|
|
|
|
**One-Tap Start:**
|
|
- Large, prominent "Start Focus" button
|
|
- Starts with most recent task
|
|
- Uses last-used interval
|
|
- Minimal friction
|
|
|
|
**Micro-Session Mode:**
|
|
- 5-minute default
|
|
- Equal reward value as longer sessions
|
|
- For "just get started" moments
|
|
- Count toward totals and momentum
|
|
|
|
**"Just Start" Mode:**
|
|
- Permission to stop after 5 minutes
|
|
- No completion pressure
|
|
- Often leads to continued work
|
|
- Celebrate initiation, not just completion
|
|
|
|
**Guided Start (Optional):**
|
|
- Brief energy check-in
|
|
- Task selection (or "Continue last task")
|
|
- Interval suggestion
|
|
- Start confirmation
|
|
|
|
#### 6.2.5 Visual Timer
|
|
|
|
**Progress Ring (Primary):**
|
|
- Circular progress indicator
|
|
- Fills clockwise as time passes
|
|
- No countdown numbers required
|
|
- Gentle color shift (cool to warm)
|
|
- Optional: percentage remaining
|
|
|
|
**Color Gradient Mode:**
|
|
- Background color shifts
|
|
- Cool colors (blue, green) → Warm colors (orange, red)
|
|
- Peripheral awareness sufficient
|
|
- Reduced anxiety vs. countdown
|
|
|
|
**Nature Metaphor Mode:**
|
|
- Growing plant/tree (Forest-inspired but gentler)
|
|
- Water filling a container
|
|
- Sunrise/sunset cycle
|
|
- Engaging without pressure
|
|
|
|
**Configuration:**
|
|
- Users choose preferred timer style
|
|
- Can switch modes anytime
|
|
- Accessibility options (larger text, high contrast)
|
|
|
|
#### 6.2.6 Growth Visualization (Garden)
|
|
|
|
**Concept:**
|
|
- Visual representation of focus history
|
|
- Garden that grows as you complete sessions
|
|
- Plants, flowers, trees unlocked over time
|
|
- Environment evolves based on engagement patterns
|
|
|
|
**Implementation:**
|
|
- Completion unlocks new plants
|
|
- Variety based on session types
|
|
- Seasonal themes refresh periodically
|
|
- No penalty for gaps (garden doesn't die)
|
|
|
|
**Psychological Basis:**
|
|
- Ownership + accumulation = CD4 (Ownership Core Drive)
|
|
- Visual progress = Endowed Progress Effect
|
|
- Permanent accumulation = ownership, not anxiety
|
|
|
|
**Comparison to Forest:**
|
|
- Forest: Tree dies if you fail → punishment (CD8)
|
|
- Pomodoro-Mate: Garden grows with completion → celebration (CD4)
|
|
- Forest: Dead trees visible → shame
|
|
- Pomodoro-Mate: Gaps don't remove plants → forgiveness
|
|
|
|
#### 6.2.7 Fresh Start + Momentum
|
|
|
|
**Daily Reset:**
|
|
- Every day is a clean slate
|
|
- Yesterday's incomplete sessions don't dominate UI
|
|
- New empty progress bar
|
|
- Encouraging "Day 1" messaging for returns
|
|
|
|
**Momentum Score (Not Streaks):**
|
|
- Percentage-based (0-100%)
|
|
- Decays slowly on missed days (not reset to zero)
|
|
- Recovery path is clear
|
|
- Never lose everything
|
|
|
|
**Momentum Mechanics:**
|
|
- Daily engagement: +5-10% to momentum
|
|
- Missed day: -10-15% decay (not reset)
|
|
- Return after gap: Welcome back bonus (+20%)
|
|
- Multiple return: Bonus increases
|
|
|
|
**Grace Period:**
|
|
- Configurable grace days
|
|
- Completing 1 session preserves momentum
|
|
- "Streak saved!" notification
|
|
- Doesn't demand perfection
|
|
|
|
**Achievement History:**
|
|
- Visible record of past successes
|
|
- "Your best week was 47 sessions"
|
|
- "You've focused for 100+ hours total"
|
|
- Evidence of capability during self-doubt
|
|
|
|
---
|
|
|
|
## 7. ADHD-Optimized Design Requirements
|
|
|
|
### 7.1 Design Principles
|
|
|
|
| Principle | Implementation |
|
|
|-----------|---------------|
|
|
| **Meet users where they are** | Start with shorter intervals, adapt to capacity |
|
|
| **Reduce cognitive load** | Minimize decisions required, automate where possible |
|
|
| **Make failure recoverable** | Never create permanent setbacks |
|
|
| **Externalize executive function** | Timer handles time-tracking, queue handles task routing |
|
|
| **Honor natural rhythms** | Adapt to energy fluctuations, don't impose rigid structure |
|
|
| **Provide immediate feedback** | Instant rewards, no delayed gratification |
|
|
| **Support transitions** | Rituals and prompts for work/break transitions |
|
|
| **Respect autonomy** | Suggest, don't impose; trust user judgment |
|
|
|
|
### 7.2 Feature Specifications
|
|
|
|
#### 7.2.1 Task Initiation Support
|
|
|
|
**Micro-Commitment:**
|
|
- "Just 2 minutes" or "Just open the document"
|
|
- Reduced activation energy
|
|
- Often leads to continued work
|
|
|
|
**Task Decomposition Helper:**
|
|
- "Write report" → "1) Create outline, 2) Write intro..."
|
|
- Each sub-task fits one Pomodoro
|
|
- Reduces overwhelm
|
|
|
|
**"What's the First Step?" Prompt:**
|
|
- When staring at task list without starting
|
|
- Prompt: "What's the tiniest first step?"
|
|
- Start micro-session for just that step
|
|
|
|
**Quick-Start Mode:**
|
|
- One-tap resume with last task
|
|
- No navigation required
|
|
- "Continue where you left off"
|
|
|
|
#### 7.2.2 Distraction Management
|
|
|
|
**Distraction Capture Pad:**
|
|
- Quick-entry field during sessions
|
|
- "Park" intrusive thoughts
|
|
- Review later, not during session
|
|
- Implements Cirillo's distraction sheet digitally
|
|
|
|
**Environmental Suggestions:**
|
|
- Non-intrusive tips: "Consider putting your phone in another room"
|
|
- Not强制性的
|
|
- Based on detected distraction patterns
|
|
|
|
#### 7.2.3 Break Optimization
|
|
|
|
**Break Activity Menu:**
|
|
- Pre-defined appropriate activities
|
|
- Physical movement prioritized
|
|
- Low-dopamine options
|
|
- Eliminated decision during break
|
|
|
|
**Sample Menu:**
|
|
```
|
|
Quick Break (2-3 min):
|
|
☐ 10 deep breaths
|
|
☐ Look out window (20 feet away)
|
|
☐ Sip water slowly
|
|
☐ Gentle stretch
|
|
|
|
Medium Break (5-7 min):
|
|
☐ Walk to get water
|
|
☐ 10 jumping jacks
|
|
☐ Quick stretch routine
|
|
☐ Bathroom break + water
|
|
|
|
Long Break (10-15 min):
|
|
☐ Walk around block
|
|
☐ Make a drink
|
|
☐ Full stretch routine
|
|
☐ Quick phone check (timer)
|
|
```
|
|
|
|
**Return Ritual Prompt:**
|
|
- Guided transition back to work
|
|
- Deep breath, state intention
|
|
- Review where you left off
|
|
|
|
#### 7.2.4 Hyperfocus Handling
|
|
|
|
**Flow Detection:**
|
|
- Keyboard/mouse activity during session
|
|
- User confirmation: "Are you in the zone?"
|
|
- Offer extension without forcing break
|
|
|
|
**Hyperfocus Mode:**
|
|
- Option to disable timer when in flow
|
|
- Manual break initiation
|
|
- Trust user's judgment
|
|
|
|
**Gentle Upper Limit:**
|
|
- Soft reminder at 90 minutes
|
|
- "You've been working for a while. Remember to hydrate."
|
|
- Not强制性的
|
|
|
|
**Post-Hyperfocus Support:**
|
|
- Break enforcement option
|
|
- Reminders for basic needs
|
|
- Gentle return to structured intervals
|
|
|
|
#### 7.2.5 Timer Anxiety Mitigation
|
|
|
|
**Visual Timer Options:**
|
|
- Progress ring (fills, no countdown numbers)
|
|
- Color gradient (ambient awareness)
|
|
- Hide seconds option
|
|
- Hide timer option (just alerts)
|
|
|
|
**Sound Options:**
|
|
- Gentle, non-jarring sounds
|
|
- Volume control
|
|
- Vibration-only mode
|
|
- Test sounds in settings
|
|
|
|
**Pressure-Free Framing:**
|
|
- "Focus session" not "Pomodoro"
|
|
- "When ready" not "Must complete"
|
|
- "Your choice" not "You should"
|
|
|
|
#### 7.2.6 Mood-Adaptive Interface
|
|
|
|
**Calm Mode:**
|
|
- Simplified interface when struggling
|
|
- Soft colors, minimal animations
|
|
- Reassuring copy
|
|
- Reduced metrics visibility
|
|
|
|
**Energy Mode:**
|
|
- More dynamic interface when on a roll
|
|
- Brighter colors, celebratory feedback
|
|
- Full metrics visible
|
|
- Momentum encouragement
|
|
|
|
**One-Tap Mode Switching:**
|
|
- "I'm overwhelmed" → Calm mode
|
|
- "I'm feeling focused" → Energy mode
|
|
- No menu navigation required
|
|
|
|
#### 7.2.7 Externalized Executive Function
|
|
|
|
**Task Queue Management:**
|
|
- Auto-advance to next task
|
|
- Remove "what should I work on?" burden
|
|
- Quick reorder when priorities shift
|
|
|
|
**Session State Persistence:**
|
|
- Session survives app exit
|
|
- Resume prompt on return
|
|
- Never lose progress accidentally
|
|
|
|
**Automatic Break Timing:**
|
|
- Break timer starts automatically
|
|
- Gentle transition prompts
|
|
- Removes "should I take a break?" decision
|
|
|
|
**Progress Reminders:**
|
|
- External cues for breaks
|
|
- Not intrusive
|
|
- Support without nagging
|
|
|
|
---
|
|
|
|
## 8. Gamification Framework
|
|
|
|
### 8.1 Design Philosophy
|
|
|
|
**Outcome Over Output:**
|
|
- Measure growth, sustainability, and well-being — not just activity counts
|
|
- Rewards for resilience, recovery, and consistency — not just completion
|
|
- Progress visualization that emphasizes trajectory — not just daily scores
|
|
|
|
**White-Hat Drives Over Black-Hat:**
|
|
- Primary: Epic Meaning, Development, Creativity, Ownership, Social (supportive)
|
|
- Secondary: Unpredictability (surprise rewards)
|
|
- Minimal: Loss/Avoidance, Scarcity
|
|
|
|
**Forgiveness Architecture:**
|
|
- Momentum decay instead of streak reset
|
|
- Recovery rewards instead of gap penalties
|
|
- Welcome back messaging instead of shame
|
|
|
|
### 8.2 Points System
|
|
|
|
#### 8.2.1 Earning Points
|
|
|
|
| Action | Points | Rationale |
|
|
|--------|--------|-----------|
|
|
| Complete any session | 10 | Basic participation |
|
|
| Micro-session (5-10 min) | 10 | Equal value (initiation is hardest) |
|
|
| Extended session (45+ min) | 15 | Deep work recognition |
|
|
| Energy check-in | 2 | Self-awareness rewarded |
|
|
| Focus quality rating | 2 | Reflection valued |
|
|
| Distraction captured | 1 | Implementing technique properly |
|
|
| Break taken | 5 | Rest is productive |
|
|
| Rest day (no sessions) | 10 | Recovery celebrated |
|
|
| Return after 3-day gap | 20 | Resumption is huge |
|
|
| Return after 7-day gap | 30 | Major resilience |
|
|
| Return after 14-day gap | 40 | Phoenix return |
|
|
| Return after 30-day gap | 50 | Maximum recognition |
|
|
| Insight recorded | 5 | Learning valued |
|
|
| Weekly review completed | 15 | Reflection practice |
|
|
|
|
#### 8.2.2 Spending Points
|
|
|
|
| Reward | Cost | Type |
|
|
|--------|------|------|
|
|
| New garden theme | 50-100 | Cosmetic |
|
|
| Timer sound pack | 30 | Cosmetic |
|
|
| Extended break (5 extra min) | 20 | Functional |
|
|
| Focus report (weekly insights) | 40 | Learning |
|
|
| Donation to charity | 100 | Meaning |
|
|
| Custom break activity | 30 | Personalization |
|
|
|
|
#### 8.2.3 Point Rules
|
|
|
|
- Points never expire (reduces pressure)
|
|
- No caps on earning (encourages engagement)
|
|
- Framing: "Points are tools, not goals"
|
|
|
|
### 8.3 Achievement System
|
|
|
|
#### 8.3.1 Achievement Categories
|
|
|
|
**1. Getting Started (Onboarding)**
|
|
| Achievement | Description | Unlocks |
|
|
|-------------|-------------|---------|
|
|
| First Focus | Complete your first session | Basic functionality |
|
|
| First Three | Complete 3 sessions | Garden plants unlocked |
|
|
| Week Starter | Use app 3 days in first week | Themes unlocked |
|
|
|
|
**2. Consistency (Not Perfection)**
|
|
| Achievement | Description | Threshold |
|
|
|-------------|-------------|-----------|
|
|
| Week Warrior | Complete 5 sessions in a week | 5/week |
|
|
| Month Master | Complete 20 sessions in a month | 20/month |
|
|
| Steady Progress | 4+ weeks of any activity | 4 weeks |
|
|
| Quarter Champion | Use app for 13+ weeks | 13 weeks |
|
|
|
|
**3. Recovery and Resilience**
|
|
| Achievement | Description | Threshold |
|
|
|-------------|-------------|-----------|
|
|
| Comeback Kid | Return after 3+ day gap | Return |
|
|
| Phoenix | Return after 14+ day gap | Return |
|
|
| Never Give Up | Return after 30+ day gap | Return |
|
|
| Bounce Back | Recover momentum 3 times | Recovery |
|
|
|
|
**4. Self-Awareness**
|
|
| Achievement | Description | Threshold |
|
|
|-------------|-------------|-----------|
|
|
| Energy Expert | Complete 20 energy check-ins | 20 check-ins |
|
|
| Pattern Finder | View 5 insight reports | 5 reports |
|
|
| Reflection Regular | Complete 10 weekly reviews | 10 reviews |
|
|
|
|
**5. Rest and Recovery**
|
|
| Achievement | Description | Threshold |
|
|
|-------------|-------------|-----------|
|
|
| Rest Day Champion | Take 1 rest day | Rest |
|
|
| Balance Master | Equal work and rest days in a week | Balance |
|
|
| Sustainable Pace | 4 weeks without burnout signals | Sustained |
|
|
|
|
**6. Learning and Growth**
|
|
| Achievement | Description | Threshold |
|
|
|-------------|-------------|-----------|
|
|
| Estimation Pro | Accurate estimates 10 times | Est accuracy |
|
|
| Focus Finder | Complete 10 extended sessions | Deep work |
|
|
| Task Completer | Complete 50 tasks | Task mastery |
|
|
|
|
**7. Connection (Future)**
|
|
| Achievement | Description | Threshold |
|
|
|-------------|-------------|-----------|
|
|
| Body Double | Complete 5 co-working sessions | Social |
|
|
| Support Circle | Join 1 community challenge | Community |
|
|
|
|
#### 8.3.2 Achievement Display
|
|
|
|
- **Trophy Case:** Visual collection of earned achievements
|
|
- **Framing:** "Growth milestones, not performance metrics"
|
|
- **No leaderboards:** Personal achievement, not competition
|
|
|
|
### 8.4 Progress Visualization
|
|
|
|
#### 8.4.1 Daily View
|
|
|
|
- Today's sessions (progress bar)
|
|
- Rest days taken (highlighted positively)
|
|
- Energy trend (line graph)
|
|
- Focus quality (line graph)
|
|
- **No streak display**
|
|
|
|
#### 8.4.2 Weekly View
|
|
|
|
- Bar chart of daily sessions
|
|
- Pattern highlights
|
|
- "You focused best on Tuesday this week"
|
|
- Weekly insight generated
|
|
|
|
#### 8.4.3 Monthly View
|
|
|
|
- Calendar heatmap (activity by day)
|
|
- Pattern recognition
|
|
- Trend direction
|
|
- Month-over-month comparison
|
|
|
|
#### 8.4.4 Multi-Dimensional Progress
|
|
|
|
- Four progress bars:
|
|
- Focus Work (sessions completed)
|
|
- Rest & Recovery (rest days taken)
|
|
- Learning & Insights (insights recorded)
|
|
- Connection (social interactions — future)
|
|
- All equally prominent
|
|
- Balance celebrated
|
|
|
|
### 8.5 Social Features
|
|
|
|
#### 8.5.1 Body Doubling Rooms
|
|
|
|
- Virtual co-working presence
|
|
- Optional video/audio
|
|
- Scheduled or drop-in
|
|
- No performance tracking
|
|
- Privacy-first
|
|
|
|
#### 8.5.2 Support Circles (Future)
|
|
|
|
- Small groups (5-8 users)
|
|
- Weekly check-ins
|
|
- Share struggles and wins equally
|
|
- Trained moderators
|
|
|
|
#### 8.5.3 Cooperative Challenges (Future)
|
|
|
|
- Group goals (everyone contributes)
|
|
- No internal ranking
|
|
- Shared celebration
|
|
- "Our circle completed 500 sessions this week"
|
|
|
|
#### 8.5.4 Encouragement System
|
|
|
|
- Pre-written supportive messages
|
|
- "You've got this!"
|
|
- "Proud of you for returning"
|
|
- No performance comparisons
|
|
|
|
### 8.6 Anti-Patterns (Explicitly Avoid)
|
|
|
|
| Anti-Pattern | Why Avoid | Alternative |
|
|
|-------------|-----------|------------|
|
|
| Binary streak reset | Shame spiral | Momentum decay |
|
|
| Dead tree / punishing visuals | Anxiety | Garden that grows |
|
|
| Global leaderboards | Demoralization | Personal progress |
|
|
| Points that expire | Pressure | Permanent points |
|
|
| "You failed" language | Shame | "Let's try again" |
|
|
| Feature lock behind paywall | Trust break | Core free, advanced paid |
|
|
| Dark patterns / manipulation | Ethics | Transparent design |
|
|
|
|
---
|
|
|
|
## 9. User Journey
|
|
|
|
### 9.1 Onboarding Flow
|
|
|
|
#### Day 1: Welcome and Setup
|
|
|
|
**Step 1: Welcome (2 minutes)**
|
|
- Warm welcome messaging
|
|
- "This isn't about perfection. It's about progress."
|
|
- Brief value proposition
|
|
|
|
**Step 2: Understanding (2 minutes)**
|
|
- Optional: "Would you like to tell us about your focus challenges?" (skip option)
|
|
- Normalize struggles: "Many people with focus challenges find this helpful"
|
|
- No pressure to disclose diagnosis
|
|
|
|
**Step 3: Assessment (3 minutes)**
|
|
- Energy patterns: Morning / Afternoon / Evening / Variable
|
|
- Past struggles: What hasn't worked? (multi-select)
|
|
- Goals: What do you want to achieve? (multi-select)
|
|
|
|
**Step 4: Setup (3 minutes)**
|
|
- Suggested session length (based on assessment)
|
|
- Timer style preference
|
|
- Notification preferences
|
|
|
|
**Step 5: First Session (5-15 minutes)**
|
|
- Guided first session
|
|
- Celebration on completion
|
|
- Set expectation: "One session = success"
|
|
|
|
#### Week 1: Foundation Building
|
|
|
|
**Day 2-3: Establishing**
|
|
- Daily check-in prompt
|
|
- Suggest completing 1-2 sessions
|
|
- Offer micro-session if resistance detected
|
|
|
|
**Day 4-5: Pattern Recognition**
|
|
- First insights generated
|
|
- "You're completing most sessions in the morning"
|
|
- Encourage reflection
|
|
|
|
**Day 6-7: First Week Review**
|
|
- Weekly summary
|
|
- Celebrate consistency
|
|
- Identify what worked
|
|
|
|
#### Month 1: Habit Formation
|
|
|
|
**Week 2-3: Momentum Building**
|
|
- Encourage 3-5 sessions per week
|
|
- Introduce momentum tracking
|
|
- Address any struggles
|
|
|
|
**Week 4: Month Review**
|
|
- Monthly summary
|
|
- Achievement recognition
|
|
- Adjust goals for Month 2
|
|
|
|
### 9.2 Daily Flow
|
|
|
|
#### Morning/Start
|
|
|
|
1. **App Open**
|
|
- Energy check-in prompt (optional but encouraged)
|
|
- "How are you feeling? (1-5 scale)"
|
|
- Suggested session length based on energy
|
|
|
|
2. **Task Selection**
|
|
- View task queue
|
|
- Quick-add new tasks
|
|
- Drag to reorder
|
|
|
|
3. **Session Start**
|
|
- One-tap start with selected task
|
|
- Or quick-start with last task
|
|
- Timer begins
|
|
|
|
#### During Session
|
|
|
|
1. **Timer Display**
|
|
- Visual timer (progress ring, color gradient)
|
|
- Optional: current task visible
|
|
- Optional: hide timer
|
|
|
|
2. **Distraction Capture**
|
|
- Side panel for intrusive thoughts
|
|
- Quick note without leaving timer
|
|
- Review later
|
|
|
|
3. **Extension Option**
|
|
- Easy +5, +15, +30 minute buttons
|
|
- "Are you in the zone?" prompt
|
|
- User choice, not enforcement
|
|
|
|
#### Session End
|
|
|
|
1. **Completion Celebration**
|
|
- Brief animation/sound
|
|
- Points awarded
|
|
- "Great work!"
|
|
|
|
2. **Quick Reflection**
|
|
- Focus quality rating (1-5)
|
|
- Distractions captured (count)
|
|
- Notes (optional)
|
|
|
|
3. **Break Prompt**
|
|
- Suggested break activity
|
|
- Break timer start
|
|
- Or skip to next task
|
|
|
|
#### End of Day
|
|
|
|
1. **Daily Summary**
|
|
- Sessions completed
|
|
- Time focused
|
|
- Momentum update
|
|
- Celebration framing
|
|
|
|
2. **Weekly Preview**
|
|
- Tomorrow's suggested focus times
|
|
- Upcoming tasks
|
|
- No pressure messaging
|
|
|
|
### 9.3 Return After Gap Flow
|
|
|
|
**Detection:** User hasn't opened app in 3+ days
|
|
|
|
**On Return:**
|
|
1. **Warm Welcome**
|
|
- "Welcome back! We missed you."
|
|
- "No judgment, no pressure."
|
|
|
|
2. **Acknowledge Absence**
|
|
- "It's been a few days."
|
|
- "That's okay — life happens."
|
|
|
|
3. **Offer Support**
|
|
- "Would you like to start with a micro-session?"
|
|
- Adjust expectations
|
|
|
|
4. **Incentivize Return**
|
|
- Return bonus: 20-50 points
|
|
- Achievement unlocked: "Comeback Kid"
|
|
|
|
5. **Re-onboarding (Light)**
|
|
- Remind of key features
|
|
- Adjust goals if needed
|
|
- Fresh start messaging
|
|
|
|
---
|
|
|
|
## 10. Technical Specifications
|
|
|
|
### 10.1 Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Client Apps │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │
|
|
│ │ Web PWA │ │ iOS App │ │Android │ │ Desktop (Tauri) │ │
|
|
│ └────┬────┘ └────┬────┘ └────┬────┘ └────────┬────────┘ │
|
|
└───────┼────────────┼────────────┼─────────────────┼─────────┘
|
|
│ │ │ │
|
|
└────────────┴────────────┴─────────────────┘
|
|
│
|
|
┌─────────▼─────────┐
|
|
│ API Gateway │
|
|
│ (REST/GraphQL) │
|
|
└─────────┬─────────┘
|
|
│
|
|
┌──────────────────────┼──────────────────────┐
|
|
│ │ │
|
|
┌───────▼───────┐ ┌─────────▼─────────┐ ┌──────▼──────┐
|
|
│ Auth Service │ │ Session Service │ │ Insight │
|
|
│ (JWT/OAuth) │ │ (Core Logic) │ │ Service │
|
|
└───────────────┘ └─────────┬─────────┘ └──────┬──────┘
|
|
│ │
|
|
┌──────────▼──────────┐ ┌──────▼──────┐
|
|
│ Database │ │ Analytics │
|
|
│ (PostgreSQL) │ │ (Timescale) │
|
|
└─────────────────────┘ └─────────────┘
|
|
│
|
|
┌──────────▼──────────┐
|
|
│ File Storage │
|
|
│ (S3/Local) │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
### 10.2 Data Models
|
|
|
|
#### User
|
|
|
|
```typescript
|
|
interface User {
|
|
id: string;
|
|
email: string;
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
|
|
// Preferences
|
|
preferences: {
|
|
defaultWorkDuration: number; // minutes
|
|
defaultShortBreak: number;
|
|
defaultLongBreak: number;
|
|
longBreakInterval: number; // sessions before long break
|
|
timerStyle: 'ring' | 'gradient' | 'digital' | 'nature';
|
|
soundPack: string;
|
|
theme: string;
|
|
notificationsEnabled: boolean;
|
|
quietHoursStart?: string; // HH:mm
|
|
quietHoursEnd?: string;
|
|
};
|
|
|
|
// Gamification
|
|
points: number;
|
|
achievements: string[]; // achievement IDs
|
|
momentumScore: number; // 0-100
|
|
|
|
// Stats
|
|
totalSessions: number;
|
|
totalFocusMinutes: number;
|
|
currentStreak: number;
|
|
longestStreak: number;
|
|
lastActiveDate: Date;
|
|
}
|
|
```
|
|
|
|
#### Session
|
|
|
|
```typescript
|
|
interface Session {
|
|
id: string;
|
|
userId: string;
|
|
|
|
// Timing
|
|
startedAt: Date;
|
|
endedAt?: Date;
|
|
plannedDuration: number; // seconds
|
|
actualDuration: number; // seconds
|
|
|
|
// State
|
|
status: 'active' | 'completed' | 'abandoned' | 'extended';
|
|
|
|
// Context
|
|
taskId?: string;
|
|
intervalType: 'work' | 'shortBreak' | 'longBreak';
|
|
|
|
// Quality
|
|
qualityRating?: number; // 1-5
|
|
distractionsCount: number;
|
|
|
|
// Metadata
|
|
deviceType: string;
|
|
extensionUsed: boolean;
|
|
extendedMinutes: number;
|
|
}
|
|
```
|
|
|
|
#### Task
|
|
|
|
```typescript
|
|
interface Task {
|
|
id: string;
|
|
userId: string;
|
|
|
|
title: string;
|
|
notes?: string;
|
|
|
|
// Estimation
|
|
estimatedPomodoros: number;
|
|
actualPomodoros: number;
|
|
|
|
// Organization
|
|
status: 'pending' | 'inProgress' | 'completed' | 'archived';
|
|
resistanceLevel?: 'low' | 'medium' | 'high';
|
|
|
|
// Timing
|
|
createdAt: Date;
|
|
completedAt?: Date;
|
|
|
|
// Pomodoros
|
|
pomodoros: string[]; // Session IDs
|
|
}
|
|
```
|
|
|
|
#### Distraction
|
|
|
|
```typescript
|
|
interface Distraction {
|
|
id: string;
|
|
userId: string;
|
|
sessionId: string;
|
|
|
|
note: string;
|
|
createdAt: Date;
|
|
|
|
// Resolution
|
|
resolved: boolean;
|
|
resolvedAt?: Date;
|
|
}
|
|
```
|
|
|
|
### 10.3 API Endpoints
|
|
|
|
#### Authentication
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| POST | `/auth/register` | Create account |
|
|
| POST | `/auth/login` | Login |
|
|
| POST | `/auth/logout` | Logout |
|
|
| POST | `/auth/refresh` | Refresh token |
|
|
| POST | `/auth/forgot-password` | Password reset |
|
|
| POST | `/auth/reset-password` | Set new password |
|
|
|
|
#### Sessions
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/sessions` | List sessions (with filters) |
|
|
| POST | `/sessions` | Start new session |
|
|
| GET | `/sessions/:id` | Get session details |
|
|
| PATCH | `/sessions/:id` | Update session (end, rate) |
|
|
| DELETE | `/sessions/:id` | Delete session |
|
|
|
|
#### Tasks
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/tasks` | List tasks |
|
|
| POST | `/tasks` | Create task |
|
|
| GET | `/tasks/:id` | Get task details |
|
|
| PATCH | `/tasks/:id` | Update task |
|
|
| DELETE | `/tasks/:id` | Delete task |
|
|
| POST | `/tasks/:id/complete` | Mark complete |
|
|
|
|
#### Insights
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/insights/daily` | Daily summary |
|
|
| GET | `/insights/weekly` | Weekly report |
|
|
| GET | `/insights/monthly` | Monthly report |
|
|
| GET | `/insights/patterns` | Detected patterns |
|
|
| GET | `/insights/recommendations` | AI recommendations |
|
|
|
|
#### Gamification
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/user/points` | Get points balance |
|
|
| GET | `/user/achievements` | Get achievements |
|
|
| POST | `/user/rewards/redeem` | Redeem reward |
|
|
| GET | `/user/momentum` | Get momentum score |
|
|
| GET | `/user/garden` | Get garden state |
|
|
|
|
### 10.4 Platform Strategy
|
|
|
|
| Platform | Priority | Tech Stack | Rationale |
|
|
|----------|----------|------------|------------|
|
|
| **Web (PWA)** | 1 | Next.js + React | Lowest friction, cross-platform, fast iteration |
|
|
| **iOS** | 2 | React Native | High monetization, widget support |
|
|
| **Android** | 3 | React Native | Market share, notification support |
|
|
| **macOS** | 4 | Tauri + React | Menu bar integration, power users |
|
|
| **Windows/Linux** | 5 | Tauri + React | Power users, open source community |
|
|
|
|
### 10.5 Offline-First Architecture
|
|
|
|
- All core features work offline
|
|
- Local storage primary, sync when online
|
|
- Conflict resolution: last-write-wins with merge
|
|
- Offline indicator in UI
|
|
- Background sync when connection restored
|
|
|
|
---
|
|
|
|
## 11. Non-Functional Requirements
|
|
|
|
### 11.1 Performance
|
|
|
|
| Metric | Target |
|
|
|--------|--------|
|
|
| App load time | < 2 seconds |
|
|
| Timer accuracy | < 1 second drift per hour |
|
|
| Sync latency | < 5 seconds across devices |
|
|
| Offline-to-online sync | < 10 seconds |
|
|
|
|
### 11.2 Accessibility
|
|
|
|
- WCAG 2.1 AA compliance
|
|
- Screen reader support
|
|
- Keyboard navigation
|
|
- High contrast mode
|
|
- Larger text option
|
|
- Color blind friendly (not color-dependent)
|
|
|
|
### 11.3 Security
|
|
|
|
- End-to-end encryption for sensitive data (future)
|
|
- OAuth 2.0 authentication
|
|
- JWT with refresh tokens
|
|
- Data export (GDPR compliance)
|
|
- Data deletion (right to be forgotten)
|
|
- No third-party analytics without consent
|
|
|
|
### 11.4 Privacy
|
|
|
|
- Minimal data collection
|
|
- No tracking without consent
|
|
- Local-first by default
|
|
- Optional cloud sync (encrypted)
|
|
- Transparent data policy
|
|
- Open source (auditable)
|
|
|
|
### 11.5 Reliability
|
|
|
|
- 99.5% uptime target
|
|
- Graceful degradation
|
|
- Error reporting (opt-in)
|
|
- Crash recovery
|
|
- Data backup
|
|
|
|
---
|
|
|
|
## 12. Success Metrics and KPIs
|
|
|
|
### 12.1 Primary Metrics
|
|
|
|
| Metric | Definition | Target (6 months) |
|
|
|--------|------------|-------------------|
|
|
| **Weekly Active Users (WAU)** | Unique users with 1+ session per week | 5,000 |
|
|
| **90-Day Retention** | Users active at day 90 | 25% |
|
|
| **Session Completion Rate** | Sessions completed / started | > 85% |
|
|
| **Weekly Sessions per User** | Average sessions per WAU per week | 8 |
|
|
| **Return Rate After Gap** | Users who return after 3+ day absence | > 60% |
|
|
|
|
### 12.2 User-Reported Outcomes
|
|
|
|
| Metric | Collection Method | Target |
|
|
|--------|-------------------|--------|
|
|
| **Focus Self-Efficacy** | In-app survey (1-10) | +2 points by day 30 |
|
|
| **Shame Reduction** | In-app survey | "Using this feels supportive" > 80% |
|
|
| **Tool Satisfaction** | App store review / NPS | NPS > 40 |
|
|
| **Would Recommend** | NPS question | > 50% promoters |
|
|
|
|
### 12.3 Engagement Metrics
|
|
|
|
| Metric | Definition | Target |
|
|
|--------|------------|--------|
|
|
| **Day 1 Retention** | Return on day 2 | > 50% |
|
|
| **Day 7 Retention** | Return on day 8 | > 30% |
|
|
| **Day 30 Retention** | Return on day 31 | > 15% |
|
|
| **Average Session Length** | Mean actual duration | 18-25 minutes |
|
|
| **Feature Adoption** | % using energy check-in | > 40% |
|
|
|
|
### 12.4 Technical Metrics
|
|
|
|
| Metric | Target |
|
|
|--------|--------|
|
|
| **App Store Rating** | 4.5+ stars |
|
|
| **Crash Rate** | < 0.5% |
|
|
| **Timer Accuracy** | < 0.1% drift |
|
|
| **Offline Capability** | 100% core features |
|
|
|
|
### 12.5 Gamification Health Metrics
|
|
|
|
| Metric | Target |
|
|
|--------|--------|
|
|
| **Points Earning Rate** | Increasing over time |
|
|
| **Achievement Unlock Rate** | 2+ per month per active user |
|
|
| **Garden Engagement** | > 60% visit garden weekly |
|
|
| **Momentum Recovery Rate** | > 70% return to peak after gap |
|
|
|
|
---
|
|
|
|
## 13. Launch Phases
|
|
|
|
### 13.1 Phase 1: MVP Launch (Months 1-3)
|
|
|
|
**Goal:** Launch core product, establish product-market fit
|
|
|
|
**Features:**
|
|
- Flexible interval timer (5-90 min)
|
|
- Task selection with Pomodoro estimation
|
|
- Automatic session tracking
|
|
- Visual timer (progress ring, color gradient)
|
|
- Growth visualization (basic garden)
|
|
- Fresh start + momentum tracking
|
|
- Distraction capture pad
|
|
- Session quality rating
|
|
- Basic weekly insights
|
|
|
|
**Success Criteria:**
|
|
- 1,000 WAU by end of phase
|
|
- 20% Day 30 retention
|
|
- Positive user feedback (App Store / surveys)
|
|
- < 1% crash rate
|
|
|
|
### 13.2 Phase 2: Engagement Enhancement (Months 4-6)
|
|
|
|
**Goal:** Deepen engagement, improve retention
|
|
|
|
**Features:**
|
|
- AI-powered weekly insights
|
|
- Hyperfocus-aware mode
|
|
- Energy/mood check-in
|
|
- Break activity menu
|
|
- Achievement system expansion
|
|
- Multiple garden themes
|
|
- Points shop
|
|
|
|
**Success Criteria:**
|
|
- 5,000 WAU by end of phase
|
|
- 25% Day 90 retention
|
|
- > 40% energy check-in adoption
|
|
- > 50% weekly insight view rate
|
|
|
|
### 13.3 Phase 3: Community (Months 7-12)
|
|
|
|
**Goal:** Build community, social features
|
|
|
|
**Features:**
|
|
- Body doubling rooms
|
|
- Support circles
|
|
- Cooperative challenges
|
|
- Encouragement system
|
|
- Community forum
|
|
- User-generated templates
|
|
|
|
**Success Criteria:**
|
|
- 15,000 WAU by end of phase
|
|
- > 10% social feature adoption
|
|
- Active community engagement
|
|
- Community-driven feature requests
|
|
|
|
### 13.4 Phase 4: Platform Expansion (Months 13-18)
|
|
|
|
**Goal:** Full platform coverage, enterprise features
|
|
|
|
**Features:**
|
|
- Desktop apps (macOS, Windows, Linux)
|
|
- GitHub/Jira integration
|
|
- Team features (future)
|
|
- Wearable integration
|
|
- API for developers
|
|
|
|
**Success Criteria:**
|
|
- 50,000 WAU
|
|
- Cross-platform usage
|
|
- Enterprise pilot customers
|
|
|
|
---
|
|
|
|
## 14. Ethical Considerations
|
|
|
|
### 14.1 ADHD Representation
|
|
|
|
**Do:**
|
|
- Acknowledge ADHD as neurobiological, not moral failing
|
|
- Avoid stigmatizing language
|
|
- Include diverse ADHD presentations
|
|
- Consult ADHD community in development
|
|
|
|
**Don't:**
|
|
- Use ADHD as marketing gimmick
|
|
- Over-pathologize normal human challenges
|
|
- Claim to "cure" or "fix" ADHD
|
|
- Appropriate ADHD identity without authentic representation
|
|
|
|
### 14.2 Gamification Ethics
|
|
|
|
**Do:**
|
|
- Design for user well-being, not addiction
|
|
- Be transparent about gamification mechanics
|
|
- Allow complete opt-out of gamification
|
|
- Monitor for problematic use patterns
|
|
|
|
**Don't:**
|
|
- Use dark patterns or manipulation
|
|
- Exploit loss aversion excessively
|
|
- Create artificial urgency or FOMO
|
|
- Encourage unsustainable behavior
|
|
|
|
### 14.3 Data Ethics
|
|
|
|
**Do:**
|
|
- Minimize data collection
|
|
- Provide complete data portability
|
|
- Allow complete data deletion
|
|
- Be transparent about data use
|
|
- Protect vulnerable user data
|
|
|
|
**Don't:**
|
|
- Sell user data
|
|
- Use data for advertising targeting
|
|
- Retain data longer than necessary
|
|
- Exploit mental health data
|
|
|
|
### 14.4 Accessibility Ethics
|
|
|
|
**Do:**
|
|
- Design for diverse abilities by default
|
|
- Test with users with disabilities
|
|
- Continuously improve accessibility
|
|
- Prioritize inclusive design
|
|
|
|
**Don't:**
|
|
- Treat accessibility as optional
|
|
- Use accessibility as differentiation without substance
|
|
- Ignore feedback from disabled users
|
|
|
|
---
|
|
|
|
## 15. Open Questions
|
|
|
|
### 15.1 Product Strategy
|
|
|
|
1. **Freemium Model:** What features are free vs. paid? When does premium make sense?
|
|
2. **Open Source:** How do we balance community contributions with product vision?
|
|
3. **Platform Priority:** Given limited resources, which platform should we prioritize after web?
|
|
|
|
### 15.2 Technical
|
|
|
|
4. **Data Storage:** How do we handle offline-first with cross-device sync?
|
|
5. **Timer Accuracy:** What's the acceptable drift threshold for cross-device sync?
|
|
6. **AI Insights:** What infrastructure is needed for meaningful pattern analysis?
|
|
|
|
### 15.3 Community
|
|
|
|
7. **Body Doubling:** How do we implement this respecting privacy and preventing abuse?
|
|
8. **Moderation:** How do we moderate community features without over-moderating?
|
|
9. **Accessibility:** What accessibility standards should we commit to at launch?
|
|
|
|
### 15.4 Monetization
|
|
|
|
10. **Sustainability:** What's the path to revenue? When do we need it?
|
|
11. **Pricing:** What's the right price point for premium?
|
|
12. **Enterprise:** Is enterprise a real opportunity? What's the timeline?
|
|
|
|
---
|
|
|
|
## Appendix A: Feature Comparison Matrix
|
|
|
|
| Feature | Forest | Focus To-Do | Habitica | Pomodoro-Mate |
|
|
|---------|--------|-------------|----------|---------------|
|
|
| Flexible intervals | No | Yes | N/A | **Yes (5-90)** |
|
|
| ADHD-aware design | No | No | Partial | **Yes** |
|
|
| True Pomodoro methodology | No | Partial | No | **Yes (5 phases)** |
|
|
| Outcome gamification | No | No | Partial | **Yes** |
|
|
| Forgiveness-first | No | No | No | **Yes** |
|
|
| Open source | No | No | Partial | **Yes** |
|
|
| Cross-platform | Yes | Yes | Yes | **Yes** |
|
|
| Body doubling | No | No | No | **Future** |
|
|
| AI insights | No | No | No | **Yes** |
|
|
| Distraction capture | Partial | No | No | **Yes** |
|
|
| Hyperfocus mode | No | No | No | **Yes** |
|
|
| Energy check-in | No | No | No | **Yes** |
|
|
|
|
---
|
|
|
|
## Appendix B: Research Sources
|
|
|
|
1. Market Research Studies (3 files)
|
|
- market-research-llama.md
|
|
- market-research-report.md
|
|
- market-research-glm51.md
|
|
|
|
2. ADHD Research Studies (3 files)
|
|
- study-minimax-m2.7.md
|
|
- study-qwen35.md
|
|
- study-glm51.md
|
|
|
|
3. Gamification Studies (3 files)
|
|
- gamify-minimax-m2.7.md
|
|
- gamify-qwen3.5.md
|
|
- gamify-glm51.md
|
|
|
|
---
|
|
|
|
## Appendix C: Glossary
|
|
|
|
| Term | Definition |
|
|
|------|------------|
|
|
| **Pomodoro** | 25-minute focus work session (traditionally) |
|
|
| **Momentum Score** | Percentage-based tracking (0-100) that decays slowly, never resets |
|
|
| **Body Doubling** | Virtual co-working presence for accountability |
|
|
| **Hyperfocus Mode** | Open-ended focus when user is in productive flow state |
|
|
| **Micro-Session** | 5-10 minute focus session for low-resistance starts |
|
|
| **Distraction Capture** | "Parking lot" for intrusive thoughts during sessions |
|
|
| **White-Hat Drives** | Positive motivation mechanisms (meaning, growth, ownership) |
|
|
| **Black-Hat Drives** | Urgency mechanisms (scarcity, loss, unpredictability) |
|
|
| **Cirillo's 5 Phases** | Planning, Tracking, Recording, Processing, Visualizing |
|
|
| **Output** | Tasks completed, hours logged, sessions done |
|
|
| **Outcome** | Growth, sustainability, well-being improvement |
|
|
|
|
---
|
|
|
|
*Document maintained by: Product Management Team*
|
|
*Last updated: April 2026*
|
|
*Next review: Before Phase 2 launch*
|