pomodoro-mate/docs/PRD/PRD-POMODORO-MATE-minimax2.7.md

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
2. Problem Statement
3. Target User Profile
4. Competitive Landscape
5. Product Vision and Positioning
6. Core Feature Requirements
7. ADHD-Optimized Design Requirements
8. Gamification Framework
9. User Journey
10. Technical Specifications
11. Non-Functional Requirements
12. Success Metrics and KPIs
13. Launch Phases
14. Ethical Considerations
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

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

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

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

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