santhoshj/pomodoro-mate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PRDs

Browse Source
This commit is contained in:
Santhosh Janardhanan
2026-04-04 15:04:43 -04:00
parent a48cfc031a
commit 3657b8d68c
20 changed files with 3316 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
.claude/settings.local.json Normal file
View File

@@ -0,0 +1,316 @@
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov prime --agent coordinator"
},
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov mail check --inject --agent coordinator"
}
]
}
],
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov mail check --inject --agent coordinator"
}
]
}
],
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; [ -z \"$OVERSTORY_WORKTREE_PATH\" ] && exit 0; read -r INPUT; FILE_PATH=$(echo \"$INPUT\" | sed -n 's/.*\"file_path\": *\"\\([^\"]*\\)\".*/\\1/p'); [ -z \"$FILE_PATH\" ] && exit 0; case \"$FILE_PATH\" in /*) ;; *) FILE_PATH=\"$(pwd)/$FILE_PATH\" ;; esac; case \"$FILE_PATH\" in \"$OVERSTORY_WORKTREE_PATH\"/*) exit 0 ;; \"$OVERSTORY_WORKTREE_PATH\") exit 0 ;; esac; echo '{\"decision\":\"block\",\"reason\":\"Path boundary violation: file is outside your assigned worktree. All writes must target files within your worktree.\"}';"
}
]
},
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; [ -z \"$OVERSTORY_WORKTREE_PATH\" ] && exit 0; read -r INPUT; FILE_PATH=$(echo \"$INPUT\" | sed -n 's/.*\"file_path\": *\"\\([^\"]*\\)\".*/\\1/p'); [ -z \"$FILE_PATH\" ] && exit 0; case \"$FILE_PATH\" in /*) ;; *) FILE_PATH=\"$(pwd)/$FILE_PATH\" ;; esac; case \"$FILE_PATH\" in \"$OVERSTORY_WORKTREE_PATH\"/*) exit 0 ;; \"$OVERSTORY_WORKTREE_PATH\") exit 0 ;; esac; echo '{\"decision\":\"block\",\"reason\":\"Path boundary violation: file is outside your assigned worktree. All writes must target files within your worktree.\"}';"
}
]
},
{
"matcher": "NotebookEdit",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; [ -z \"$OVERSTORY_WORKTREE_PATH\" ] && exit 0; read -r INPUT; FILE_PATH=$(echo \"$INPUT\" | sed -n 's/.*\"notebook_path\": *\"\\([^\"]*\\)\".*/\\1/p'); [ -z \"$FILE_PATH\" ] && exit 0; case \"$FILE_PATH\" in /*) ;; *) FILE_PATH=\"$(pwd)/$FILE_PATH\" ;; esac; case \"$FILE_PATH\" in \"$OVERSTORY_WORKTREE_PATH\"/*) exit 0 ;; \"$OVERSTORY_WORKTREE_PATH\") exit 0 ;; esac; echo '{\"decision\":\"block\",\"reason\":\"Path boundary violation: file is outside your assigned worktree. All writes must target files within your worktree.\"}';"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; read -r INPUT; CMD=$(echo \"$INPUT\" | sed 's/.*\"command\": *\"\\([^\"]*\\)\".*/\\1/'); if echo \"$CMD\" | grep -qE '\\bgit\\s+push\\b'; then echo '{\"decision\":\"block\",\"reason\":\"git push is blocked — use ov merge to integrate changes, push manually when ready\"}'; exit 0; fi; if echo \"$CMD\" | grep -qE 'git\\s+reset\\s+--hard'; then echo '{\"decision\":\"block\",\"reason\":\"git reset --hard is not allowed — it destroys uncommitted work\"}'; exit 0; fi; if echo \"$CMD\" | grep -qE 'git\\s+checkout\\s+-b\\s'; then BRANCH=$(echo \"$CMD\" | sed 's/.*git\\s*checkout\\s*-b\\s*\\([^ ]*\\).*/\\1/'); if ! echo \"$BRANCH\" | grep -qE '^overstory/coordinator/'; then echo '{\"decision\":\"block\",\"reason\":\"Branch must follow overstory/coordinator/{task-id} convention\"}'; exit 0; fi; fi;"
}
]
},
{
"matcher": "Task",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — Task is not allowed\"}'"
}
]
},
{
"matcher": "TeamCreate",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — TeamCreate is not allowed\"}'"
}
]
},
{
"matcher": "TeamDelete",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — TeamDelete is not allowed\"}'"
}
]
},
{
"matcher": "SendMessage",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — SendMessage is not allowed\"}'"
}
]
},
{
"matcher": "TaskCreate",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — TaskCreate is not allowed\"}'"
}
]
},
{
"matcher": "TaskUpdate",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — TaskUpdate is not allowed\"}'"
}
]
},
{
"matcher": "TaskList",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — TaskList is not allowed\"}'"
}
]
},
{
"matcher": "TaskGet",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — TaskGet is not allowed\"}'"
}
]
},
{
"matcher": "TaskOutput",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — TaskOutput is not allowed\"}'"
}
]
},
{
"matcher": "TaskStop",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Overstory agents must use '\\''ov sling'\\'' for delegation — TaskStop is not allowed\"}'"
}
]
},
{
"matcher": "AskUserQuestion",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"AskUserQuestion requires human interaction -- agents run non-interactively. Use ov mail (--type question) to escalate\"}'"
}
]
},
{
"matcher": "EnterPlanMode",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"EnterPlanMode requires human interaction -- agents run non-interactively. Use ov mail (--type question) to escalate\"}'"
}
]
},
{
"matcher": "EnterWorktree",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"EnterWorktree requires human interaction -- agents run non-interactively. Use ov mail (--type question) to escalate\"}'"
}
]
},
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"coordinator agents cannot modify files — Write is not allowed\"}'"
}
]
},
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"coordinator agents cannot modify files — Edit is not allowed\"}'"
}
]
},
{
"matcher": "NotebookEdit",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"coordinator agents cannot modify files — NotebookEdit is not allowed\"}'"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; read -r INPUT; CMD=$(echo \"$INPUT\" | sed 's/.*\"command\": *\"\\([^\"]*\\)\".*/\\1/'); if echo \"$CMD\" | grep -qE '^\\s*ov '; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*overstory '; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*bd '; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*sd '; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*git status'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*git log'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*git diff'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*git show'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*git blame'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*git branch'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*mulch '; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*git add'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*git commit'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*bun test'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*bun run lint'; then exit 0; fi; if echo \"$CMD\" | grep -qE '^\\s*bun run typecheck'; then exit 0; fi; if echo \"$CMD\" | grep -qE 'sed\\s+-i|sed\\s+--in-place|echo\\s+.*>|printf\\s+.*>|cat\\s+.*>|tee\\s|\\bvim\\b|\\bnano\\b|\\bvi\\b|\\bmv\\s|\\bcp\\s|\\brm\\s|\\bmkdir\\s|\\btouch\\s|\\bchmod\\s|\\bchown\\s|>>|\\bgit\\s+add\\b|\\bgit\\s+commit\\b|\\bgit\\s+merge\\b|\\bgit\\s+push\\b|\\bgit\\s+reset\\b|\\bgit\\s+checkout\\b|\\bgit\\s+rebase\\b|\\bgit\\s+stash\\b|\\bnpm\\s+install\\b|\\bbun\\s+install\\b|\\bbun\\s+add\\b|\\bbun\\s+-e\\b|\\bbun\\s+--eval\\b|\\bnode\\s+-e\\b|\\bnode\\s+--eval\\b|\\bdeno\\s+eval\\b|\\bpython3?\\s+-c\\b|\\bperl\\s+-e\\b|\\bruby\\s+-e\\b'; then echo '{\"decision\":\"block\",\"reason\":\"coordinator agents cannot modify files — this command is not allowed\"}'; exit 0; fi;"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; [ -z \"$OVERSTORY_TASK_ID\" ] && exit 0; read -r INPUT; CMD=$(echo \"$INPUT\" | sed 's/.*\"command\": *\"\\([^\"]*\\)\".*/\\1/'); if echo \"$CMD\" | grep -qE '^\\s*(sd|bd)\\s+close\\s'; then ISSUE_ID=$(echo \"$CMD\" | sed -E 's/^[[:space:]]*(sd|bd)[[:space:]]+close[[:space:]]+([^ ]+).*/\\2/'); if [ \"$ISSUE_ID\" != \"$OVERSTORY_TASK_ID\" ]; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"Cannot close issue $ISSUE_ID — agents may only close their own task ($OVERSTORY_TASK_ID). Report completion via worker_done mail to your parent instead.\\\"}\"; exit 0; fi; fi; if echo \"$CMD\" | grep -qE '^\\s*(sd|bd)\\s+update\\s.*--status'; then ISSUE_ID=$(echo \"$CMD\" | sed -E 's/^[[:space:]]*(sd|bd)[[:space:]]+update[[:space:]]+([^ ]+).*/\\2/'); if [ \"$ISSUE_ID\" != \"$OVERSTORY_TASK_ID\" ]; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"Cannot update issue $ISSUE_ID — agents may only update their own task ($OVERSTORY_TASK_ID).\\\"}\"; exit 0; fi; fi;"
}
]
},
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov log tool-start --agent coordinator --stdin"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; read -r INPUT; CMD=$(echo \"$INPUT\" | sed 's/.*\"command\": *\"\\([^\"]*\\)\".*/\\1/'); if echo \"$CMD\" | grep -qE '\\bgit\\s+push\\b'; then echo '{\"decision\":\"block\",\"reason\":\"git push is blocked — use ov merge to integrate changes, push manually when ready\"}'; exit 0; fi;"
}
]
}
],
"PostToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov log tool-end --agent coordinator --stdin"
},
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov mail check --inject --agent coordinator --debounce 500"
}
]
},
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov mail check --inject --agent coordinator --debounce 30000"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; read -r INPUT; if echo \"$INPUT\" | grep -qE '\\bgit\\s+commit\\b'; then ml diff HEAD~1 >/dev/null 2>&1 || true; fi; exit 0;"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "read -r INPUT; if echo \"$INPUT\" | grep -q 'git commit'; then mulch diff HEAD~1 2>/dev/null || true; fi"
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov log session-end --agent coordinator --stdin"
},
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ml learn"
}
]
}
],
"PreCompact": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "export PATH=\"$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH\"; [ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov prime --agent coordinator --compact"
}
]
}
]
}
}

1
.mulch/expertise/product.jsonl Normal file
View File

@@ -0,0 +1 @@
{"type":"decision","title":"Core product identity and tech stack","rationale":"Synthesized from 9 research documents (457KB total). Fills gap between oversimplified timers and bloated productivity suites. No competitor combines all three pillars.","classification":"foundational","recorded_at":"2026-04-04T17:16:04.988Z","id":"mx-bb21b4"}

3
.mulch/mulch.config.yaml
View File

@@ -1,5 +1,6 @@
version: '1' version: '1'
domains: [] domains:
- product
governance: governance:
max_entries: 100 max_entries: 100
warn_entries: 150 warn_entries: 150

12
.overstory/groups.json Normal file
View File

@@ -0,0 +1,12 @@
[
{
"id": "group-1b2a6875",
"name": "prd-synthesis",
"memberIssueIds": [
"pomodoro-mate-5acd"
],
"status": "completed",
"createdAt": "2026-04-04T16:43:51.684Z",
"completedAt": "2026-04-04T18:05:04.704Z"
}
]

2
.seeds/issues.jsonl
View File

@@ -1 +1 @@
{"id":"pomodoro-mate-5acd","title":"Synthesize final PRD from research docs and existing PRD drafts","status":"closed","type":"task","priority":1,"createdAt":"2026-04-04T16:42:39.943Z","updatedAt":"2026-04-04T16:55:09.573Z","closedAt":"2026-04-04T16:55:09.573Z","closeReason":"Synthesized final PRD from 9 research documents (3 market research, 3 ADHD studies, 3 gamification studies). Created docs/PRD.md (790 lines) covering: executive summary, market context, user personas, core features (timer, task management, ADHD support, gamification, analytics), technical architecture, pricing model, and 24-week roadmap. Builder prd-writer completed and merge_ready sent to coordinator."} {"id":"pomodoro-mate-5acd","title":"Synthesize final PRD from research docs and existing PRD drafts","status":"closed","type":"task","priority":1,"createdAt":"2026-04-04T16:42:39.943Z","updatedAt":"2026-04-04T17:15:32.657Z","closedAt":"2026-04-04T17:15:32.657Z","closeReason":"Merged branch overstory/prd-writer/pomodoro-mate-5acd. PRD synthesized to docs/PRD.md (790 lines)."}

68
AGENTS.md Normal file
View File

@@ -0,0 +1,68 @@
<!-- mulch:start -->
## Project Expertise (Mulch)
<!-- mulch-onboard-v:1 -->
This project uses [Mulch](https://github.com/jayminwest/mulch) for structured expertise management.
**At the start of every session**, run:
```bash
mulch prime
```
This injects project-specific conventions, patterns, decisions, and other learnings into your context.
Use `mulch prime --files src/foo.ts` to load only records relevant to specific files.
**Before completing your task**, review your work for insights worth preserving — conventions discovered,
patterns applied, failures encountered, or decisions made — and record them:
```bash
mulch record <domain> --type <convention|pattern|failure|decision|reference|guide> --description "..."
```
Link evidence when available: `--evidence-commit <sha>`, `--evidence-bead <id>`
Run `mulch status` to check domain health and entry counts.
Run `mulch --help` for full usage.
Mulch write commands use file locking and atomic writes — multiple agents can safely record to the same domain concurrently.
### Before You Finish
1. Discover what to record:
```bash
mulch learn
```
2. Store insights from this work session:
```bash
mulch record <domain> --type <convention|pattern|failure|decision|reference|guide> --description "..."
```
3. Validate and commit:
```bash
mulch sync
```
<!-- mulch:end -->
<!-- seeds:start -->
## Issue Tracking (Seeds)
<!-- seeds-onboard-v:1 -->
This project uses [Seeds](https://github.com/jayminwest/seeds) for git-native issue tracking.
**At the start of every session**, run:
```
sd prime
```
This injects session context: rules, command reference, and workflows.
**Quick reference:**
- `sd ready` — Find unblocked work
- `sd create --title "..." --type task --priority 2` — Create issue
- `sd update <id> --status in_progress` — Claim work
- `sd close <id>` — Complete work
- `sd dep add <id> <depends-on>` — Add dependency between issues
- `sd sync` — Sync with git (run before pushing)
### Before You Finish
1. Close completed issues: `sd close <id>`
2. File issues for remaining work: `sd create --title "..."`
3. Sync and push: `sd sync && git push`
<!-- seeds:end -->

70
docs/PRD/PRD-Gemini.md Normal file
View File

@@ -0,0 +1,70 @@
# Pomodoro Mate: Product Requirements Document (PRD-Gemini)
## 1. Executive Summary
Pomodoro Mate is a next-generation productivity application that addresses the critical failures of traditional Pomodoro timers by adopting an **ADHD-First Design** combined with **Outcome-Focused Gamification**. Research indicates that strict Pomodoro implementations (rigid 25-minute sessions, mandatory interruptions, consequence-based mechanics) fail up to 70% of neurodivergent users. Pomodoro Mate pivots away from traditional output tracking (sessions counted, streaks maintained) toward meaningful outcomes (sustained behavioral change, task initiation, self-efficacy, and wellness).
## 2. Problem Statement
The current landscape of productivity apps (e.g., Forest, Habitica, Focus To-Do) centers heavily on **output-focused gamification**. They rely heavily on:
- Rigid interval requirements that disrupt hyperfocus.
- Extrinsic motivation structures (e.g., punishing users by killing a virtual tree or breaking a streak).
- Competitiveness (leaderboards) which cause shame, anxiety, and eventual abandonment from users grappling with ADHD or executive dysfunction.
Pomodoro Mate resolves these issues by prioritizing flexibility, compassion-driven mechanics, and outcome-oriented progress.
## 3. Product Vision
To build the definitive productivity tool that nurtures long-term focus habits by working *with* the brain's natural neurobiology rather than against it. Pomodoro Mate measures success not by minutes logged or streaks upheld, but by the user's growing competence, well-being, and capacity for self-forgiveness.
## 4. Target Audience
1. **Primary**: Adults dealing with executive dysfunction, ADHD, or neurodivergence, who need structural scaffolding without punitive overhead.
2. **Secondary**: Software developers wanting privacy-first, workflow-integrated focus tracking (e.g., GitHub/Linear linkages without cloud telemetry).
3. **Tertiary**: Pomodoro Method adapters who desire high control over time and task configurations.
## 5. Core Value Propositions
- **Outcome-Oriented Gamification**: Replaces punishing streaks and leaderboards with meaningful visual growth, recovery badges, and trend recognition formats that minimize shame.
- **Hyperfocus Protections**: Doesn't break user flow states arbitrarily. Flexible check-ins suggest extensions over forced stops.
- **Externalized Executive Function**: Built-in distraction capture pads, micro-sessions ("just 5 mins"), and minimal-barrier task starts.
- **Privacy First**: Local-first storage with optional end-to-end (E2E) encryption, avoiding tracking and cloud subscriptions.
## 6. Key Features Pipeline
### Tier 1: MVP Core Features
| Feature | Functionality | Value Add |
|---------|---------------|-----------|
| **Flexible Timing & Micro-Sessions** | Custom interval presets (e.g., 5, 10, 20, 90 mins). "Just 5 Minutes" rapid start. | Overcomes task initiation paralysis. Fits variable ADHD attention spans. |
| **Painless Pause & Persistence** | If broken or paused, session persists without penalty or lost 'points'. | Prevents shame cycle and loss aversion. |
| **Distraction Parking Lot** | One-click entry for intrusive thoughts to be reviewed later. | Offloads working memory burden during focus. |
| **Zero-Shame Resilience Tracking** | Focuses on weekly trends and 'days active' rather than consecutive day streaks. | Eliminates the "Streak Industrial Complex" that ruins retention. |
### Tier 2: Enhanced Features
| Feature | Functionality | Value Add |
|---------|---------------|-----------|
| **Energy check-ins** | A 1-5 scale assessment that recommends optimal interval lengths dynamically. | Accommodates daily capacity and spoon theory. |
| **Hyperfocus Extension** | If the user hits their timer end but is 'in the zone', the app gently offers +15 min extensions instead of breaking workflow. | Respects the ADHD hyperfocus phenomenon. |
| **Recovery Gamification** | Achievements / points rewarded for successfully taking breaks, stretching, or honoring boundaries. | Balances outcome (well-being) against mere output (work). |
### Tier 3: Advanced Pipeline
| Feature | Functionality | Value Add |
|---------|---------------|-----------|
| **Virtual Body Doubling Integration** | Connection with peers for silent co-working via WebRTC. | Social accountability without leaderboard toxicity. |
| **Developer Ecosystem Integrations** | Ties Pomodoros directly to Git commits or Jira tickets. | Tracks coding specifics locally. |
| **Pattern Insights** | Highlights optimal personal focus times over the month via local analytics. | Builds long-term self-awareness. |
## 7. Design & Ethical Guardrails
- **No Demoralizing Mechanics**: No dead plants, broken chains, or penalizing sounds.
- **No Leaderboards**: Emphasizes community support (cooperative goals) over competitive comparison.
- **Default Forgiveness**: Each day is a fresh slate. Any dropped tasks are archived gracefully.
- **Compassionate Tone of Voice**: The app behaves like an encouraging coach, utilizing identity-based messaging ("You are someone who respects their breaks") over transactional prompts.
## 8. Technical Architecture
1. **Platform**: Web-First PWA using Next.js/React (High reach, works across platforms seamlessly). Later wrapped via Tauri for native Desktop builds.
2. **Data Model**: Local-First via IndexedDB/SQLite. Users retain ownership of their data. Cloud Sync is optional and E2E encrypted.
3. **UI / UX**: Clean, minimally distracting interfaces, supporting dark modes and sensory-friendly themes.
## 9. Success Metrics
- **Day-30 Retention**: Target >35% (overcoming the typical "novelty cliff" for ADHD users).
- **Completion Quality**: High usage of the distraction pad and break adherence.
- **Sentiment & Self-Efficacy**: Measured by optional, periodic short check-ins monitoring reduced anxiety levels related to task initiation.
---
*Created per systemic synthesis of ADHD neurobiology research, gamification market analyses, and Pomodoro-technique critical evaluations.*

1629
docs/PRD/PRD-POMODORO-MATE-minimax2.7.md Normal file
View File

File diff suppressed because it is too large Load Diff

240
docs/PRD/PRD-nemotron.md Normal file
View File

@@ -0,0 +1,240 @@
# Pomodoro Mate: Product Requirements Document
## Executive Summary
Pomodoro Mate is an ADHD-informed productivity application that reimagines the Pomodoro Technique for neurodivergent brains. Unlike traditional Pomodoro tools that assume neurotypical executive function, Pomodoro Mate is designed from the ground up to work with ADHD cognitive patterns rather than against them. It combines Cirillo's original five-phase methodology with ADHD-specific adaptations including flexible intervals, externalized executive function support, dopamine-aware reward systems, and failure-spiral prevention mechanisms.
## Problem Statement
Adults with ADHD face significant challenges with task initiation, sustained attention, time perception, and emotional regulation. Traditional productivity tools fail this population because they:
1. Assume stable self-regulation and executive function
2. Use rigid time intervals that don't match ADHD attention rhythms
3. Provide inadequate or delayed rewards that don't activate the ADHD reward pathway
4. Lack scaffolding for task initiation and transition support
5. Penalize inconsistency rather than supporting sustainable habits
6. Ignore the reality of hyperfocus and its management needs
These failures lead to abandonment, shame spirals, and reinforced feelings of inadequacy rather than productive support.
## Product Vision
To create the first productivity tool that truly understands and works with the ADHD brain—not against it—by combining scientifically valid Pomodoro methodology with ADHD-informed design principles that reduce executive function burden, honor natural cognitive rhythms, and build sustainable focus habits through compassionate, outcome-oriented gamification.
## Core Value Propositions
1. **ADHD-First Design**: Every feature is evaluated through the lens of reducing executive function burden
2. **True Pomodoro Methodology**: Complete implementation of Cirillo's five phases (planning, tracking, recording, processing, visualizing)
3. **Outcome-Oriented Gamification**: Rewards sustainable habits and personal growth, not just session counts
4. **Failure-Spiral Prevention**: Built-in mechanisms that treat inconsistency as data, not moral failure
5. **Externalized Executive Function**: Offloads cognitive operations that ADHD brains struggle with
## Target Audience
Primary: Adults (18+) with diagnosed or self-identified ADHD who struggle with task initiation, time management, and sustained focus
Secondary: Individuals with ADHD-like traits (executive function challenges, time blindness) even without formal diagnosis
Tertiary: ADHD coaches, therapists, and productivity professionals seeking effective tools for their clients
## Key Features
### Tier 1: Core Features (MVP - Must Have)
| Feature | Description | Addresses ADHD Challenge |
|---------|-------------|--------------------------|
| **Flexible Interval Selection** | Presets: 5, 10, 15, 20, 25, 30, 45, 60, 90 minutes + custom options | Time perception variability, initiation barriers |
| **One-Tap Session Start** | Continue with last task or suggested task with single tap | Task initiation paralysis |
| **External Distraction Capture** | Quick-entry field for intrusive thoughts during focus sessions | Working memory limitations, internal distractions |
| **Non-Anxious Visual Timer** | Progress ring/circle with optional numbers, configurable display | Time blindness without inducing anxiety |
| **Gentle Completion Feedback** | Satisfying animation + sound on Pomodoro completion (instant, tangible) | Underactive reward pathway |
| **Fresh Start Daily** | Clean slate each day with no carry-over of "missed" sessions | Shame cycles, perfectionism |
| **Session State Persistence** | Resume where left off after interruption without penalty | Transition difficulties |
| **"Just 5 Minutes" Micro-Sessions** | Always-available ultra-short option for high-resistance moments | Overwhelm, low energy days |
### Tier 2: Enhanced Features (Should Have)
| Feature | Description | Addresses ADHD Challenge |
|---------|-------------|--------------------------|
| **Hyperfocus-Aware Mode** | Soft check-ins offering extension rather than forced breaks | Hyperflow interruption frustration |
| **Energy/Check-In Before Sessions** | 1-10 scale assessment that suggests appropriate session length | Energy fluctuations, boom-bust cycles |
| **Mood-Adaptive Interface** | Calm mode (simplified) vs Energy mode (engaging) based on user state | Emotional dysregulation |
| **Task Breakdown Helper** | Guides user to identify "tiniest first step" for overwhelming tasks | Task initiation paralysis |
| **Achievement-Focused Summaries** | End-of-session emphasis on what was accomplished, not what wasn't | Negative focus bias, shame |
| **Configurable Sensory Settings** | Multiple timer sounds, visual themes, noise generator integration | Sensory sensitivities |
| **Adaptive Interval Recommendations** | Learns from completion patterns to suggest optimal lengths | Poor self-estimation, planning aversion |
| **Pattern Insights** | "You focus best between 9-11am" type insights from usage data | Time blindness, lack of self-knowledge |
### Tier 3: Advanced Features (Nice to Have)
| Feature | Description | Addresses ADHD Challenge |
|---------|-------------|--------------------------|
| **Virtual Body Doubling** | Presence indicators showing others currently in focus sessions | Isolation, lack of external accountability |
| **Accountability Partner System** | Share progress with designated partners (opt-in) | Need for external motivation |
| **AI Companion Mode** | Periodic encouraging check-ins and non-judgmental summaries | Lack of internal motivation, self-criticism |
| **Task Templates** | Pre-built and custom task breakdown templates for recurring activities | Planning burden, initiation difficulty |
| **Calendar/Todo Integrations** | Pull tasks from existing tools to reduce friction | Task switching costs, initiation barriers |
| **Community Challenges** | Optional group challenges for social motivation | Social motivation deficits |
| **Automatic Time Estimation** | "This task usually takes you about 3 Pomodoros" based on history | Poor time estimation, planning aversion |
| **Export & Self-Analysis Tools** | Data export for users who want deeper self-knowledge | Desire for understanding patterns |
## Design Principles & Non-Negotiables
### Core Design Principles
1. **Default to Forgiveness** - Never make users feel like failures for using the tool "differently"
2. **Meet Users Where They Are** - Start with short intervals, minimal UI, low pressure
3. **Build Self-Knowledge Automatically** - Learn patterns without requiring manual tracking
4. **Honor ADHD Rhythms** - Work with hyperfocus, not against it; respect energy fluctuations
5. **Externalize Executive Function** - Assume users cannot self-regulate; provide external supports
6. **Create Dopamine Micro-Rewards** - Make completion feel good, immediately and tangibly
7. **Measure What Matters** - Track meaningful metrics, avoid shame-inducing statistics
8. **Design for Restart, Not Perfection** - Make restart easy and welcoming, avoid shame-inducing messaging
### Absolute Non-Negotiables
1. **Never shame the user** - No red X marks, no "you failed" messages, no guilt-inducing metrics
2. **Always allow a fresh start** - Every session, every day, every week is a clean slate
3. **Default to short and achievable** - Err on the side of too-easy rather than too-hard
4. **Make starting frictionless** - Path from "decide to work" to "working" should be as short as possible
5. **Respect hyperfocus** - When user is productively engaged, don't force interruption
6. **Adapt, don't impose** - Learn from user's patterns and adapt recommendations—don't impose fixed structure
7. **Accomplishment over compliance** - Measure and celebrate what was done, not what wasn't
## Technical Architecture
### Platform Strategy
1. **Web First** - Universal access, ideal for body doubling features
2. **Mobile (iOS/Android)** - Always accessible, native notifications
3. **Desktop (Mac/Windows/Linux)** - Deep work sessions
4. **Browser Extension** - Quick access, website blocking capabilities
5. **Smart Watch** - Quick timer control, break reminders
### Data Architecture
- **Local-first storage** - Works offline, with optional cloud sync
- **Encryption** - At rest and in transit
- **Privacy-focused** - Minimal data collection, no selling, user control over export/delete
- **Backup** - Automatic and user-initiated with easy restore
### Key Technical Components
1. **Timer System** - Accurate timing with multiple display options (progress bar, countdown, minimal)
2. **Break System** - Configurable durations with activity menus and transition support
3. **Task Management** - Simple creation with slicing helper, parking lot for distractions
4. **Motivation System** - Points, achievements, streaks with freeze options, challenges
5. **Tracking & Insights** - Energy/focus check-ins, correlation analysis, trend visualization
6. **Customization** - Themes, sounds, language tone options, accessibility features
7. **Social Features** - Body doubling, accountability partnerships, community features
8. **Integrations** - Calendar, task management tools, website blocking, health platforms, automation
## Success Metrics & Validation Approach
### Engagement Metrics
- **Day 7 Retention**: 50%+ (habit formation beginning)
- **Day 30 Retention**: 35%+ (past novelty period)
- **Day 90 Retention**: 25%+ (long-term sustainability)
- **Sessions per Week**: 10+ (average meaningful usage)
- **Session Completion Rate**: 80%+ (system supporting follow-through)
- **Feature Adoption**: 60%+ using ≥3 features (system flexibility valued)
### Outcome Metrics
- **Self-Reported Productivity**: 30% improvement (weekly survey)
- **Task Completion Rate**: 25% improvement (user tracking)
- **Time Management Confidence**: 40% improvement (monthly survey)
- **ADHD Symptom Interference**: 20% improvement (ASRS scale)
- **System Satisfaction**: NPS 50+, positive qualitative themes
- **Anxiety Around Productivity**: 30% reduction (survey)
### Qualitative Indicators - Positive Signals
- "This system understands me"
- "I can restart after a break without guilt"
- "The flexibility makes it sustainable"
- "I'm getting things done without burnout"
- "Finally a productivity tool that works for my brain"
### Qualitative Indicators - Concern Signals
- "It's helping but I still feel guilty when I miss"
- "I want more structure/rigidity" (may indicate mismatch)
- "The gamification is distracting"
- "I abandoned it after 2 weeks" (novelty wear-off)
- "It feels like another thing I'm failing at"
## Implementation Roadmap
### Phase 1: MVP (Months 1-3)
**Goal**: Prove core value proposition
**Features**:
- Flexible timer (5-60 min, presets + custom)
- Basic break reminders
- Session tracking (count only)
- Simple statistics (sessions today, this week)
- Customizable alerts
- Dark/light mode
**Success Metrics**:
- 50%+ Day 7 retention
- 30%+ Day 30 retention
- 4+ star average rating
- Positive qualitative feedback on flexibility
### Phase 2: ADHD Enhancements (Months 4-6)
**Goal**: Differentiate for ADHD audience
**Features**:
- Energy check-in and suggestions
- Break menu system
- Distraction capture (parking lot)
- Task slicing helper
- Gamification (points, basic achievements)
- Customizable themes
- Transition rituals
**Success Metrics**:
- Improved retention vs. Phase 1
- ADHD user testimonials
- Feature adoption rates
- Session completion rates
### Phase 3: Advanced Features (Months 7-12)
**Goal**: Comprehensive ADHD productivity system
**Features**:
- Body doubling integration
- Accountability partner features
- Advanced analytics and insights
- Third-party integrations
- AI-powered recommendations
- Community features
- Seasonal challenges
**Success Metrics**:
- Industry recognition
- Professional recommendations (ADHD coaches)
- Long-term retention (90+ days)
- Word-of-mouth growth
### Phase 4: Ecosystem (Year 2+)
**Goal**: Platform and integrations
**Features**:
- API for third-party developers
- Enterprise/team features
- Research partnerships
- Clinical validation studies
- Integration with treatment programs
**Success Metrics**:
- Research publications
- Clinical adoption
- Enterprise contracts
- Ecosystem growth
## Competitive Differentiation
| Feature | Pomodoro Mate | Forest | Focus To-Do | Habitica | Flowkeeper |
|---------|---------------|--------|-------------|----------|------------|
| **True Pomodoro Methodology** | ✅ Complete (all 5 phases) | ❌ Timer only | ⚠️ Partial | ❌ None | ✅ Complete |
| **ADHD-First Design** | ✅ Ground-up for EF challenges | ❌ Neurotypical + loss aversion | ❌ Neurotypical + basic tracking | ⚠️ Community aspects only | ❌ Neurotypical |
| **Outcome Gamification** | ✅ Habits & growth focus | ❌ Time-in-session only | ⚠️ Basic streaks | ✅ RPG system | ❌ None |
| **Flexible Intervals** | ✅ 5-90 min + adaptive | ❌ Fixed 25 min | ✅ Limited options | ❌ Fixed intervals | ❌ Fixed intervals |
| **Task Initiation Support** | ✅ Scaffolding & micro-sessions | ❌ None | ❌ None | ❌ None | ❌ None |
| **Hyperfocus Protection** | ✅ Detection & extension | ❌ None | ❌ None | ❌ None | ❌ None |
| **Failure-Spiral Prevention** | ✅ Fresh start, no guilt | ❌ Penalties for missing | ❌ Basic streaks | ❌ Penalty-based | ❌ None |
| **Externalized EF** | ✅ Distraction pad, auto-queue | ⚠️ Enforced focus only | ❌ None | ✅ Structure only | ❌ None |
| **Open Source** | ✅ Yes | ❌ No | ❌ No | ❌ No | ✅ Yes |
| **Cross-Platform** | ✅ Web-first, multi-platform | ✅ Mobile-focused | ✅ All platforms | ✅ All platforms | ❌ Desktop only |
## Conclusion
Pomodoro Mate represents a paradigm shift in productivity tool design for neurodivergent users. By grounding every feature decision in ADHD neurology and cognitive psychology—rather than adapting neurotypical tools—it addresses the root causes of productivity challenges rather than just symptoms. The combination of true Pomodoro methodology, ADHD-informed adaptations, and outcome-oriented gamification creates a unique value proposition unmatched in the current market.
The tool doesn't just help users complete more sessions; it helps them build sustainable focus habits, improve self-efficacy, and develop a healthier relationship with productivity—all while working with their brain's natural rhythms rather than fighting against them.

977
docs/PRD/PRD-qwen3.5.md Normal file
View File

@@ -0,0 +1,977 @@
# Pomodoro-Mate: Product Requirements Document
**Version:** 1.0
**Date:** April 4, 2026
**Status:** Draft for Review
**Prepared By:** Product Team
**Based On:** Comprehensive research synthesis from 9 AI-conducted studies
---
## Document Control
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2026-04-04 | Product Team | Initial draft based on research synthesis |
---
## Table of Contents
1. [Executive Summary](#1-executive-summary)
2. [Product Vision](#2-product-vision)
3. [Problem Statement](#3-problem-statement)
4. [Target Users](#4-target-users)
5. [Competitive Landscape](#5-competitive-landscape)
6. [Unique Value Propositions](#6-unique-value-propositions)
7. [Product Principles](#7-product-principles)
8. [Feature Requirements](#8-feature-requirements)
9. [Technical Requirements](#9-technical-requirements)
10. [Success Metrics](#10-success-metrics)
11. [Go-to-Market Strategy](#11-go-to-market-strategy)
12. [Roadmap](#12-roadmap)
13. [Risks and Mitigations](#13-risks-and-mitigations)
14. [Appendices](#14-appendices)
---
## 1. Executive Summary
### 1.1 Product Overview
**Pomodoro-Mate** is an open-source, ADHD-first Pomodoro timer that faithfully implements Francesco Cirillo's original Pomodoro Technique while incorporating outcome-focused gamification and modern cross-platform design.
### 1.2 Market Opportunity
The Pomodoro timer market is **saturated but undifferentiated**:
- 500+ apps exist across platforms
- Most are simple timers without methodology depth
- No app combines: True Pomodoro + ADHD-first design + Outcome gamification
- Clear gap between oversimplified timers and bloated productivity suites
### 1.3 Key Differentiators
| Differentiator | Description | Competitive Advantage |
|---------------|-------------|----------------------|
| **ADHD-First Design** | Built from ground up for executive function challenges | No competitor is ADHD-first |
| **True Pomodoro** | Faithful implementation of all 6 steps + 5 phases | Most apps are timers only |
| **Outcome Gamification** | Rewards growth, not just sessions completed | Competitors use shallow PBL |
| **Open Source** | Community-driven, transparent, privacy-respecting | Only Marinara/Pomolectron are OSS |
| **Cross-Platform** | Web-first PWA + native desktop apps | Most are platform-limited |
### 1.4 Business Model
**Freemium with Ethical Limits:**
- **Free Tier:** Unlimited Pomodoros, basic stats, local storage, all core features
- **Pro Tier ($3.99/month or $29.99/year):** Cloud sync, advanced analytics, integrations, team features
- **No artificial limits** on core functionality (unlike competitors)
### 1.5 Success Metrics (24 Months)
| Metric | 6 Months | 12 Months | 24 Months |
|--------|----------|-----------|-----------|
| Active Users | 1,000 | 5,000 | 20,000 |
| Pro Conversion | 5% | 7% | 10% |
| GitHub Stars | 200 | 500 | 2,000 |
| 90-Day Retention | 40% | 50% | 60% |
| App Store Rating | 4.5+ | 4.7+ | 4.8+ |
---
## 2. Product Vision
### 2.1 Vision Statement
> **Pomodoro-Mate helps users become focused people, not just complete more sessions.**
### 2.2 Long-Term Vision (5 Years)
Become the definitive Pomodoro tool for:
- Knowledge workers with focus challenges (especially ADHD)
- Developers seeking workflow-integrated focus
- Teams practicing synchronized deep work
- Privacy-conscious users seeking transparent tools
### 2.3 Product Pillars
```
┌─────────────────┐
│ Pomodoro-Mate │
└────────┬────────┘
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ True │ │ ADHD- │ │ Outcome │
│ Pomodoro │ │ First │ │ Gamification│
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
│ │ │
▼ ▼ ▼
• 6 Steps • Flexible • Growth-focused
• 5 Phases intervals rewards
• Interruption • Initiation • Identity-based
tracking scaffolding progression
• Estimation • Hyperfocus • No shame
feedback preservation mechanics
```
---
## 3. Problem Statement
### 3.1 Core Problems
| Problem | Impact | Evidence |
|---------|--------|----------|
| **Existing Pomodoro apps are just timers** | Users don't build lasting focus habits | 90% of apps ignore Cirillo's 5 phases |
| **ADHD users are underserved** | 4-5% of adults have ADHD; no major app is ADHD-first | Research shows 60-70% abandonment within 1 month |
| **Gamification is shallow** | Streaks create shame, points feel meaningless | 80% of apps use problematic streak mechanics |
| **Cross-platform sync is broken** | Timer drift, state inconsistency across devices | Top user complaint across all app reviews |
| **Privacy concerns** | Cloud dependency, data collection | Growing demand for local-first tools |
### 3.2 User Pain Points (from Research)
**ADHD-Specific:**
- Task initiation paralysis ("I know what to do but can't start")
- Time blindness ("Where did 2 hours go?")
- Hyperfocus interruption ("Timer rang during flow—wanted to throw computer")
- Break derailment ("5-min break became 45 minutes")
- Novelty wear-off ("Worked for 2 weeks, then abandoned")
- Shame spirals ("Missed one day, streak gone, why try?")
**General Productivity:**
- Timer anxiety (countdown creates stress)
- Feature bloat (overwhelming before even starting)
- No methodology guidance (just a countdown)
- Poor break enforcement (skip breaks, burn out)
- No estimation improvement (keep underestimating tasks)
### 3.3 Opportunity Size
| Segment | Size | Willingness to Pay |
|---------|------|-------------------|
| ADHD adults (US) | 10-12 million | High (desperate for solutions) |
| Knowledge workers | 50+ million (US) | Medium-High |
| Developers | 25+ million (global) | High (productivity = income) |
| Students | 100+ million (global) | Low-Medium |
| Remote teams | Growing rapidly | High (team licenses) |
---
## 4. Target Users
### 4.1 Primary Personas
#### Persona 1: Alex (ADHD Knowledge Worker)
| Attribute | Description |
|-----------|-------------|
| **Age** | 32 |
| **Occupation** | Marketing Manager |
| **Diagnosis** | ADHD-C (Combined) |
| **Pain Points** | Task initiation, time blindness, shame from failed systems |
| **Goals** | Build sustainable focus habits, reduce anxiety |
| **Tech Savvy** | Medium |
| **Platform** | Mac + iPhone |
| **Quote** | "I've tried every productivity app. They all work for 2 weeks then I abandon them." |
**Needs from Pomodoro-Mate:**
- Flexible intervals (some days 10 min is max)
- No shame mechanics (streak-free or forgiveness model)
- Task initiation scaffolding ("What's the tiniest first step?")
- Hyperfocus preservation (don't interrupt flow)
- Mood-adaptive interface (calm mode for overwhelmed days)
---
#### Persona 2: Sam (Software Developer)
| Attribute | Description |
|-----------|-------------|
| **Age** | 28 |
| **Occupation** | Full-Stack Developer |
| **Diagnosis** | None (focus challenges from context switching) |
| **Pain Points** | GitHub/Jira context switching, meeting fragmentation |
| **Goals** | Deep work blocks, accurate time tracking for billing |
| **Tech Savvy** | High |
| **Platform** | Linux + Windows + Android |
| **Quote** | "I need a timer that understands my workflow, not another generic app." |
**Needs from Pomodoro-Mate:**
- GitHub/Linear integration
- Terminal/CLI option
- Accurate time tracking for client billing
- App blocking during deep work
- Open source (auditable, self-hostable)
---
#### Persona 3: Jordan (Graduate Student)
| Attribute | Description |
|-----------|-------------|
| **Age** | 24 |
| **Occupation** | PhD Student |
| **Diagnosis** | ADHD-I (Inattentive) |
| **Pain Points** | Dissertation writing, procrastination, isolation |
| **Goals** | Complete dissertation, build consistent work habits |
| **Tech Savvy** | Medium-High |
| **Platform** | Windows + Android |
| **Quote** | "I need accountability without judgment. Writing is lonely." |
**Needs from Pomodoro-Mate:**
- Body doubling (virtual co-working)
- Accountability partner features
- Long-form writing support (extended sessions)
- Progress visualization (motivation during long projects)
- Free tier (student budget)
---
### 4.2 User Segments
| Segment | Priority | Characteristics | Monetization |
|---------|----------|-----------------|--------------|
| **ADHD Knowledge Workers** | Primary | High need, high willingness to pay | Pro tier |
| **Developers** | Primary | Tech-savvy, value open source | Pro tier (integrations) |
| **Students** | Secondary | Budget-conscious, high volume | Free → Pro after graduation |
| **Remote Teams** | Tertiary | Enterprise pricing potential | Team licenses |
| **Pomodoro Purists** | Niche | Value authenticity over features | Pro tier |
---
## 5. Competitive Landscape
### 5.1 Competitive Map
```
HIGH PRICE
│
Session │ Flow
($4.99/mo) │ ($6.99/mo)
│
────────────────────┼────────────────────
│
Forest │ Pomodone
($3.99) │ ($4.96/mo)
│
────────────────────┼────────────────────
│
Pomofocus │ Focus To-Do
(Free) │ (Free tier)
│
Focus Keeper │ Pomodoro-Mate
(Free) │ (Free/$3.99)
│
LOW PRICE
SIMPLE ─────────────────────────── FEATURE-RICH
│
True Pomodoro
ADHD-First
Outcome Gamification
```
### 5.2 Feature Comparison Matrix
| Feature | Forest | Focus To-Do | Session | Super Productivity | Goodtime | **Pomodoro-Mate** |
|---------|--------|-------------|---------|-------------------|----------|-------------------|
| **Core Timer** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **True Pomodoro (6 steps)** | ❌ | Partial | ❌ | ✅ | ✅ | ✅ |
| **5 Phases Implementation** | ❌ | ❌ | ❌ | Partial | ❌ | ✅ |
| **ADHD-First Design** | ❌ | ❌ | ❌ | ❌ | Partial | ✅ |
| **Flexible Intervals** | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Task Initiation Scaffolding** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| **Hyperfocus Mode** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| **Outcome Gamification** | Partial | ❌ | ❌ | ❌ | ❌ | ✅ |
| **Streak-Free Tracking** | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| **Body Doubling** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| **GitHub/Jira Integration** | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ |
| **Open Source** | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| **Cross-Platform Sync** | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ |
| **Privacy-First** | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| **AI Coaching** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
### 5.3 Competitive Weaknesses to Exploit
| Competitor | Weakness | Our Advantage |
|------------|----------|---------------|
| **Forest** | Gamification over methodology, not ADHD-aware | True Pomodoro + ADHD design |
| **Focus To-Do** | Feature bloat, dated UI, not ADHD-aware | Clean UX + ADHD-first |
| **Session** | Apple-only, expensive, analytics overwhelm | Cross-platform + affordable |
| **Super Productivity** | Complex, recent redesign backlash | Simpler + stable |
| **Goodtime** | Mobile-only, no gamification | Cross-platform + outcome gamification |
---
## 6. Unique Value Propositions
### 6.1 UVP 1: "The First Methodology-Complete Pomodoro Tool"
**Claim:** Pomodoro-Mate is the only timer that digitally implements all 6 steps and 5 phases of Francesco Cirillo's original Pomodoro Technique.
**Features:**
- Planning phase: Guided task selection with Pomodoro estimation
- Tracking phase: Automatic effort tracking during sessions
- Recording phase: Structured daily archives (automatic, no manual effort)
- Processing phase: AI-powered pattern analysis
- Visualizing phase: Growth metaphors + trend charts + predictive planning
**Messaging:**
> "Most Pomodoro apps are just timers. Pomodoro-Mate is the complete methodology—digitally implemented for the first time."
---
### 6.2 UVP 2: "ADHD-First, Not ADHD-Afterthought"
**Claim:** Pomodoro-Mate is designed from the ground up for users with executive function challenges, not adapted from neurotypical tools.
**Features:**
- Flexible intervals (5-45 min) with adaptive recommendations
- Task initiation scaffolding ("What's the tiniest first step?")
- Hyperfocus detection and preservation
- Failure-spiral prevention (fresh starts, no penalties)
- Mood-adaptive interface (calm mode vs energy mode)
- Body doubling (virtual and accountability partners)
- Executive function externalization (distraction pad, auto task queue)
**Messaging:**
> "Finally, a productivity tool that understands your brain. Built for ADHD, not adapted from neurotypical designs."
---
### 6.3 UVP 3: "Outcome Gamification, Not Output Gamification"
**Claim:** Pomodoro-Mate's gamification rewards sustainable focus habits and personal growth, not just sessions completed.
**Features:**
- Rewards consistency rhythm, not session count
- Identity-based progression ("Deep Worker"), not point accumulation
- Growth metaphors that accumulate permanently, never subtract
- Self-defined reward shops connected to real desires
- Recovery as a first-class feature, not a hack
**Messaging:**
> "Don't just count sessions. Become a focused person. Our gamification rewards who you're becoming, not just what you're doing."
---
### 6.4 UVP 4: "Open Source and Community-Driven"
**Claim:** Pomodoro-Mate is the only open-source Pomodoro tool with modern design, ADHD awareness, and cross-platform support.
**Features:**
- Community can contribute ADHD-specific features
- Transparency in how gamification mechanics work (no dark patterns)
- Self-hostable option for privacy-conscious users
- Plugin/extension architecture for community-built integrations
**Messaging:**
> "Transparent, auditable, community-driven. No dark patterns, no data selling, no locked features."
---
### 6.5 UVP 5: "Bridging Solo Focus and Social Accountability"
**Claim:** Pomodoro-Mate uniquely offers both solo deep focus and social accountability within one tool.
**Features:**
- Solo mode: Full methodology, gamification, ADHD support
- Body doubling: Virtual presence of others focusing
- Accountability partnerships: Paired progress sharing
- Community challenges: Cooperative (not competitive) goals
**Messaging:**
> "Focus alone together. Get the benefits of accountability without the pressure of competition."
---
## 7. Product Principles
### 7.1 Design Principles
| Principle | Description | Example |
|-----------|-------------|---------|
| **Forgiveness Over Punishment** | Never shame the user for missing sessions | No streak resets; "Welcome back" messaging |
| **Flexibility Over Rigidity** | Adapt to user's capacity, not vice versa | Energy-based interval suggestions |
| **Simplicity Over Complexity** | Default to simple; optional depth | One-tap start; advanced settings hidden |
| **Outcome Over Output** | Measure growth, not just activity | "Your focus capacity increased 40%" |
| **Privacy Over Convenience** | Local-first; cloud is optional | All data stored locally by default |
| **Accessibility Over Aesthetics** | Function over form (but both matter) | High contrast mode, screen reader support |
### 7.2 ADHD-Specific Principles
| Principle | Description | Implementation |
|-----------|-------------|----------------|
| **Reduce Initiation Friction** | Task initiation is the hardest part | One-tap start, micro-session option |
| **Externalize Executive Function** | Don't rely on impaired internal systems | Auto task queue, distraction pad, break enforcement |
| **Honor Hyperfocus** | Don't interrupt precious flow states | Extension options, soft alerts |
| **Prevent Shame Spirals** | ADHD users are shame-prone | No failure states, fresh start mechanics |
| **Maintain Novelty** | ADHD brains habituate quickly | Rotating themes, seasonal events |
| **Support Transitions** | Work→break→work transitions are hard | Guided return rituals, transition prompts |
### 7.3 Ethical Principles
| Principle | Description | Guardrail |
|-----------|-------------|-----------|
| **No Dark Patterns** | Never manipulate users into engagement | No fake urgency, no guilt messaging |
| **No Exploitative Gamification** | Avoid addiction mechanics | No variable ratio rewards, no loot boxes |
| **Transparent Data Practices** | Users own their data | Clear export, delete, privacy policies |
| **Accessibility Commitment** | Serve all users | WCAG 2.1 AA compliance |
| **Sustainable Engagement** | Long-term use over short-term metrics | Design for 66+ day habit formation |
---
## 8. Feature Requirements
### 8.1 Feature Prioritization Framework
**MoSCoW Method:**
- **Must Have (P0):** Critical for MVP, non-negotiable
- **Should Have (P1):** Important but not critical for launch
- **Could Have (P2):** Desirable, post-MVP
- **Won't Have (P3):** Explicitly deferred
---
### 8.2 MVP Features (P0 - Must Have)
#### 8.2.1 Core Timer
| Feature | Description | Acceptance Criteria |
|---------|-------------|---------------------|
| **Flexible Intervals** | 5, 10, 15, 25, 45, 90 min presets | User can select any preset before session |
| **Visual Timer** | Progress ring (non-anxious display) | No countdown numbers by default; optional |
| **Session Start** | One-tap start with last task | Single tap initiates session |
| **Session Extension** | +5, +15, +30 min buttons during session | Extension available without stopping |
| **Break Timer** | Auto-start 5-min break after session | Break begins automatically; gentle alert |
| **Long Break** | 15-30 min after 4 sessions | Auto-detected; user can adjust |
| **Gentle Alerts** | Soft completion sounds | Multiple sound options; no jarring alarms |
---
#### 8.2.2 Task Management
| Feature | Description | Acceptance Criteria |
|---------|-------------|---------------------|
| **Task Selection** | Choose task before session | Task list with one-tap selection |
| **Pomodoro Estimation** | Estimate sessions per task | "How many Pomodoros?" prompt |
| **Task Queue** | Ordered list of tasks | Drag-and-drop reordering |
| **Distraction Pad** | Capture intrusive thoughts | Quick-entry field; saves for later |
---
#### 8.2.3 ADHD-Specific Features
| Feature | Description | Acceptance Criteria |
|---------|-------------|---------------------|
| **Micro-Session Option** | 5-10 min sessions for low-energy days | Preset available; counts toward totals |
| **Energy Check-In** | 1-5 scale before session | Optional prompt; influences suggestions |
| **Calm Mode** | Simplified UI for overwhelmed days | Toggle reduces visual complexity |
| **Fresh Start** | Daily reset without guilt | New day = clean slate visually |
---
#### 8.2.4 Gamification (Outcome-Focused)
| Feature | Description | Acceptance Criteria |
|---------|-------------|---------------------|
| **Points System** | Earn points for sessions + wellness | Points awarded immediately on completion |
| **Growth Metaphor** | Visual garden/landscape that grows | Persistent; never decays or dies |
| **Achievement Badges** | Milestone celebrations | Focus on growth, recovery, consistency |
| **Session Summary** | Celebratory end-of-session recap | Emphasizes what was done, not missed |
---
#### 8.2.5 Progress Tracking
| Feature | Description | Acceptance Criteria |
|---------|-------------|---------------------|
| **Session History** | List of completed sessions | Date, duration, task, quality rating |
| **Weekly Overview** | Bar chart of sessions by day | No judgment on gaps |
| **Momentum Score** | Consistency percentage (not streaks) | Decays slowly; recovers quickly |
| **Export Data** | CSV/JSON export | User owns their data |
---
#### 8.2.6 Settings & Preferences
| Feature | Description | Acceptance Criteria |
|---------|-------------|---------------------|
| **Timer Sounds** | Multiple sound options | Gentle chimes, ambient sounds, silence |
| **Visual Themes** | Light, dark, warm, minimal | At least 4 themes |
| **Notifications** | Configurable reminders | Opt-in; supportive language |
| **Privacy Settings** | Local-only vs. sync | Clear toggle; defaults to local |
---
### 8.3 Post-MVP Features (P1 - Should Have)
| Feature | Description | Priority | Target Release |
|---------|-------------|----------|----------------|
| **Hyperfocus Mode** | Open-ended sessions with check-ins | High | v1.1 |
| **Body Doubling** | Virtual co-working rooms | High | v1.2 |
| **Accountability Partners** | Paired progress sharing | High | v1.2 |
| **AI Insights** | Pattern analysis ("You focus best at 10am") | High | v1.3 |
| **Task Templates** | Pre-populated sub-tasks | Medium | v1.1 |
| **Break Activity Menu** | Suggested break activities | Medium | v1.1 |
| **Return Ritual** | Guided transition back to work | Medium | v1.1 |
| **GitHub Integration** | Track commits per Pomodoro | Medium | v1.4 |
| **Linear/Jira Integration** | Auto-log time to tickets | Medium | v1.4 |
| **Mood Tracking** | Quick 1-5 rating | Medium | v1.1 |
| **Pattern Visualization** | "You're most productive on Tuesdays" | Medium | v1.3 |
| **Ambient Sounds** | Built-in noise generator | Low | v1.2 |
| **Custom Themes** | User-created themes | Low | v1.5 |
---
### 8.4 Future Features (P2 - Could Have)
| Feature | Description | Priority | Target Release |
|---------|-------------|----------|----------------|
| **Team Focus Rooms** | Synchronized team sessions | Low | v2.0 |
| **Community Challenges** | Cooperative group goals | Low | v2.0 |
| **Wearable Integration** | Apple Watch, Oura HRV data | Low | v2.1 |
| **Calendar Integration** | Session scheduling, conflict detection | Low | v1.5 |
| **AI Session Planner** | Break goals into Pomodoros | Low | v1.4 |
| **Plugin Architecture** | Community-built extensions | Low | v2.0 |
| **Self-Hosted Sync** | User's own cloud sync | Low | v2.1 |
| **Terminal/CLI App** | Developer-focused interface | Low | v1.5 |
---
### 8.5 Explicitly Deferred Features (P3 - Won't Have)
| Feature | Reason for Deferral |
|---------|---------------------|
| **Full Project Management** | Out of scope; dilutes focus |
| **Competitive Leaderboards** | Anti-pattern for ADHD; shame-inducing |
| **Financial Penalties** | Anxiety-inducing (e.g., Beeminder model) |
| **Site/App Blocking** | Forest and extensions do this well |
| **Video/Audio Calls** | Too complex; Focusmate owns this |
| **Financial/Time Tracking for Billing** | Toggl dominates; not our core |
---
## 9. Technical Requirements
### 9.1 Platform Strategy
| Platform | Priority | Technology | Target Release |
|----------|----------|------------|----------------|
| **Web (PWA)** | P0 | Next.js + PWA | MVP |
| **macOS** | P0 | Tauri or Native Swift | v1.0 |
| **iOS** | P1 | Native Swift | v1.1 |
| **Windows** | P1 | Tauri | v1.1 |
| **Android** | P2 | Native Kotlin or Flutter | v1.3 |
| **Linux** | P2 | Tauri or Native GTK | v1.3 |
| **CLI** | P3 | Rust or Python | v2.0 |
**Rationale:** Web-first for lowest friction; macOS second (highest willingness to pay); iOS for companion use; Windows/Linux for broader reach.
---
### 9.2 Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Frontend │
├─────────────────────────────────────────────────────────┤
│ Web (Next.js PWA) │ Desktop (Tauri) │ Mobile │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Sync Layer (Optional) │
├─────────────────────────────────────────────────────────┤
│ • E2E Encrypted Sync │ • Conflict Resolution │
│ • User's Own Cloud │ • Offline-First │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Local Storage │
├─────────────────────────────────────────────────────────┤
│ • SQLite (Desktop) │ • IndexedDB (Web) │
│ • CoreData (iOS) │ • Room (Android) │
└─────────────────────────────────────────────────────────┘
```
---
### 9.3 Technical Requirements
| Requirement | Specification | Rationale |
|-------------|---------------|-----------|
| **Offline-First** | Full functionality without internet | Privacy, reliability, travel |
| **Sync Latency** | <5 second drift across devices | Top user complaint in market |
| **Data Export** | CSV + JSON export | User owns their data |
| **E2E Encryption** | If cloud sync is used | Privacy-first positioning |
| **No Telemetry** | No analytics without explicit consent | Trust differentiator |
| **Open Source** | MIT or GPL license | Community trust, contributions |
| **Accessibility** | WCAG 2.1 AA compliance | Serve all users |
| **Performance** | <100ms interaction latency | ADHD users need instant feedback |
---
### 9.4 Tech Stack Recommendation
| Layer | Technology | Rationale |
|-------|------------|-----------|
| **Web Frontend** | Next.js 14 + TypeScript | Fast, SEO-friendly, PWA support |
| **Desktop** | Tauri v2 | Smaller than Electron, Rust backend |
| **Mobile (iOS)** | Swift + SwiftUI | Native performance, best UX |
| **Mobile (Android)** | Kotlin + Jetpack Compose | Native performance |
| **Local DB** | SQLite (Desktop), IndexedDB (Web) | Mature, offline-first |
| **Sync Backend** | Supabase or Self-Hosted | E2E encryption support |
| **State Management** | Zustand or Jotai | Lightweight, simple |
| **Styling** | Tailwind CSS + Framer Motion | Rapid development, animations |
| **Testing** | Vitest + Playwright | Fast, reliable |
| **CI/CD** | GitHub Actions | Free for open source |
---
### 9.5 Security Requirements
| Requirement | Implementation |
|-------------|----------------|
| **Data Encryption** | AES-256 for local storage |
| **Sync Encryption** | E2E with user-controlled keys |
| **Authentication** | Optional; email or OAuth |
| **Session Management** | Secure tokens, auto-expiry |
| **Privacy Compliance** | GDPR, CCPA ready |
| **Vulnerability Disclosure** | Security.txt, responsible disclosure |
---
## 10. Success Metrics
### 10.1 North Star Metric
**90-Day Active Users with 20+ Sessions**
*Rationale:* Captures both adoption (active) and habit formation (20+ sessions indicates real use, not just download).
---
### 10.2 Key Performance Indicators (KPIs)
| Category | Metric | Target | Measurement |
|----------|--------|--------|-------------|
| **Acquisition** | Weekly Signups | 200/week by Month 6 | Analytics |
| **Activation** | First Session Completion | 80% of signups | In-app event |
| **Retention** | Day 7 Retention | 50% | Cohort analysis |
| **Retention** | Day 30 Retention | 35% | Cohort analysis |
| **Retention** | Day 90 Retention | 25% | Cohort analysis |
| **Engagement** | Sessions per User per Week | 10+ | In-app tracking |
| **Engagement** | Session Completion Rate | 85% | Timer events |
| **Monetization** | Free → Pro Conversion | 5% by Month 6 | Stripe analytics |
| **Monetization** | Pro Retention (Monthly) | 90% | Stripe analytics |
| **Satisfaction** | App Store Rating | 4.7+ | App Store |
| **Satisfaction** | NPS | 50+ | In-app survey |
| **Community** | GitHub Stars | 500+ by Month 12 | GitHub API |
| **Community** | Contributors | 10+ by Month 12 | GitHub API |
---
### 10.3 Outcome Metrics (ADHD-Specific)
| Metric | Description | Target |
|--------|-------------|--------|
| **Resumption Rate** | % of users returning after 3+ day gap | 70% (industry avg: 40%) |
| **Streak-Free Engagement** | Users who engage without streak pressure | 60% of active users |
| **Calm Mode Usage** | % using calm mode at least once/week | 40% (indicates overwhelm support) |
| **Micro-Session Usage** | % using 5-10 min sessions | 50% (indicates initiation support) |
| **Hyperfocus Extension** | % extending sessions | 30% (indicates flow preservation) |
| **Self-Reported Focus Improvement** | User surveys | 60% report improvement at 90 days |
---
### 10.4 Anti-Metrics (What We Don't Optimize)
| Metric | Why We Avoid It |
|--------|-----------------|
| **Daily Active Users (DAU)** | Encourages daily pressure; ADHD users need flexibility |
| **Session Length Maximization** | Longer ≠ better; sustainable is better |
| **Streak Length** | Creates shame; we use momentum scores instead |
| **Time in App** | We want users focusing, not app-fiddling |
| **Notification Open Rate** | Can become manipulative; opt-in only |
---
## 11. Go-to-Market Strategy
### 11.1 Launch Phases
#### Phase 1: Soft Launch (Month 1-2)
- **Goal:** Validate core functionality, gather feedback
- **Channels:** GitHub, Reddit (r/ADHD, r/productivity), Twitter
- **Target:** 100 active users
- **Budget:** $0 (organic)
#### Phase 2: Public Launch (Month 3)
- **Goal:** Broad awareness, press coverage
- **Channels:** Product Hunt, Hacker News, tech blogs
- **Target:** 1,000 active users in first month
- **Budget:** $2,000 (Product Hunt ads, influencer outreach)
#### Phase 3: Growth (Month 4-12)
- **Goal:** Sustainable growth, community building
- **Channels:** SEO, content marketing, partnerships
- **Target:** 5,000 active users by Month 12
- **Budget:** $5,000/month (content, ads)
---
### 11.2 Distribution Channels
| Channel | Priority | Strategy | Expected Contribution |
|---------|----------|----------|----------------------|
| **Product Hunt** | High | Launch day campaign | 500 users day 1 |
| **GitHub** | High | Open source credibility | 200 stars Month 1 |
| **App Store (macOS)** | High | Paid discovery | 30% of Pro users |
| **App Store (iOS)** | High | Companion app discovery | 20% of users |
| **Reddit** | Medium | Community engagement | 100 users/month |
| **Twitter/X** | Medium | Developer audience | 50 users/month |
| **SEO** | Long-term | "Best Pomodoro app" keywords | 200 users/month by Month 6 |
| **Partnerships** | Medium | ADHD orgs, productivity influencers | 100 users/month |
---
### 11.3 Pricing Strategy
| Tier | Price | Features | Target Segment |
|------|-------|----------|----------------|
| **Free** | $0 | Unlimited Pomodoros, basic stats, local storage, all core features | Students, budget-conscious, trialing |
| **Pro (Monthly)** | $3.99/month | Cloud sync, advanced analytics, integrations, team features | Knowledge workers, professionals |
| **Pro (Annual)** | $29.99/year ($2.50/month) | Same as monthly | Committed users, better value |
| **Team** | $9.99/user/month | Admin dashboard, team analytics, shared challenges | Remote teams, accountability groups |
| **Student** | $1.99/month | Pro features at discount | Students with .edu email |
**Pricing Rationale:**
- Undercuts Session ($4.99/month) and Flow ($6.99/month)
- Annual plan offers 37% discount (industry standard)
- Free tier has no artificial limits (unlike Focus Booster's 20 sessions/month)
- Student pricing acknowledges budget constraints
---
### 11.4 Marketing Messaging
#### Primary Message
> "Pomodoro-Mate: The Pomodoro tool that understands your brain."
#### Secondary Messages
- "Finally, a productivity app designed for ADHD, not adapted from neurotypical designs."
- "True Pomodoro methodology, digitally implemented for the first time."
- "Outcome-focused gamification that rewards who you're becoming, not just what you're doing."
- "Open source, privacy-first, community-driven."
#### ADHD-Specific Messaging
- "Task initiation paralysis? We've got scaffolding for that."
- "Hyperfocus is precious. We don't interrupt it."
- "Missed days happen. We celebrate your return, not shame your gap."
- "Your brain isn't broken. Your tools were."
---
## 12. Roadmap
### 12.1 Release Timeline
```
2026
├── Q2 (Apr-Jun)
│ ├── MVP Development
│ └── Soft Launch (GitHub, Reddit)
│
├── Q3 (Jul-Sep)
│ ├── v1.0 Public Launch
│ ├── macOS App
│ └── iOS App
│
├── Q4 (Oct-Dec)
│ ├── v1.1 Hyperfocus Mode + AI Insights
│ ├── Windows App
│ └── GitHub/Linear Integrations
│
2027
├── Q1 (Jan-Mar)
│ ├── v1.2 Body Doubling + Accountability Partners
│ ├── Android App
│ └── Team Features (Beta)
│
├── Q2 (Apr-Jun)
│ ├── v1.3 Pattern Visualization + Wearable Integration
│ └── Linux App
│
└── Q3 (Jul-Sep)
├── v2.0 Team Launch + Plugin Architecture
└── CLI App
```
---
### 12.2 MVP Scope (v1.0)
| Feature | Status | Owner | Target Date |
|---------|--------|-------|-------------|
| Core Timer (flexible intervals) | Not Started | Dev Team | 2026-05-15 |
| Task Selection + Estimation | Not Started | Dev Team | 2026-05-15 |
| Visual Timer (progress ring) | Not Started | Dev Team | 2026-05-15 |
| Session History + Export | Not Started | Dev Team | 2026-05-15 |
| Points System (outcome-focused) | Not Started | Dev Team | 2026-05-15 |
| Growth Metaphor (garden) | Not Started | Design Team | 2026-05-15 |
| Calm Mode | Not Started | Dev Team | 2026-05-15 |
| Energy Check-In | Not Started | Dev Team | 2026-05-15 |
| Web App (PWA) | Not Started | Dev Team | 2026-05-30 |
| macOS App | Not Started | Dev Team | 2026-06-15 |
---
### 12.3 Post-MVP Priorities
| Priority | Feature | Effort | Impact | Target Release |
|----------|---------|--------|--------|----------------|
| P1 | Hyperfocus Mode | Medium | High | v1.1 |
| P1 | Body Doubling | High | High | v1.2 |
| P1 | AI Insights | Medium | High | v1.3 |
| P1 | GitHub Integration | Medium | High | v1.4 |
| P2 | Accountability Partners | Medium | Medium | v1.2 |
| P2 | iOS App | High | High | v1.1 |
| P2 | Windows App | Medium | Medium | v1.1 |
| P2 | Android App | High | Medium | v1.3 |
| P3 | Team Features | High | Medium | v2.0 |
| P3 | CLI App | Low | Low | v2.0 |
---
## 13. Risks and Mitigations
### 13.1 Market Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| **Market Saturation** | High | Medium | Niche focus (ADHD, developers); clear differentiation |
| **Feature Copying** | High | Low | Speed, community, brand loyalty; open source moat |
| **Monetization Failure** | Medium | High | Freemium with clear value; reasonable pricing |
| **Platform Dependency** | Medium | Medium | Web-first; avoid single-platform lock-in |
---
### 13.2 Technical Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| **Sync Complexity** | High | High | Start with local-first; add sync post-MVP |
| **Performance Issues** | Medium | High | Performance budgets; early load testing |
| **Security Vulnerabilities** | Medium | High | Security audits; bug bounty program |
| **Cross-Platform Inconsistency** | High | Medium | Shared codebase (Tauri); design system |
---
### 13.3 Business Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| **Founder Burnout** | Medium | High | Open source community; phased launch; co-founders |
| **Regulatory Changes** | Low | Medium | GDPR/CCPA compliance from day 1 |
| **Economic Downturn** | Medium | Low | Productivity tools are counter-cyclical; affordable pricing |
---
### 13.4 ADHD-Specific Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| **Novelty Wear-Off** | High | High | Built-in novelty maintenance (themes, events) |
| **Shame Spiral from Bugs** | Medium | High | Forgiving error messages; easy recovery |
| **Complexity Overwhelm** | Medium | High | Default simplicity; progressive disclosure |
| **Community Toxicity** | Low | High | Clear code of conduct; active moderation |
---
## 14. Appendices
### Appendix A: Research Sources
This PRD is based on synthesis of 9 comprehensive research documents:
1. **study-qwen35.md** - ADHD Neuroscience Deep Dive (94KB)
2. **study-glm51.md** - ADHD + Pomodoro Design Study (64KB)
3. **study-minimax-m2.7.md** - ADHD + Pomodoro Framework (57KB)
4. **gamify-qwen3.5.md** - Outcome Gamification Research (64KB)
5. **gamify-minimax-m2.7.md** - Gamification Psychology (46KB)
6. **gamify-glm51.md** - Gamification Overview (20KB)
7. **market-research-report.md** - Competitive Landscape (64KB)
8. **market-research-glm51.md** - Market Gaps Analysis (20KB)
9. **market-research-llama.md** - Pomodoro Authenticity Study (28KB)
**Total Research:** 457KB across 9 documents
---
### Appendix B: User Research Quotes
**From ADHD Studies:**
> "I know I should start. I want to start. I'm sitting here ready to start. But I can't make myself begin."
> — Task initiation paralysis
> "I was in the zone, finally making real progress. Then the timer went off and I wanted to throw my computer across the room."
> — Hyperfocus interruption
> "This system was amazing for two weeks! I was so productive. Now I can't even look at the app."
> — Novelty wear-off
> "I had a 100-day streak and lost it due to a family emergency. Never opened the app again."
> — Streak shame spiral
---
### Appendix C: Competitive Feature Matrix (Full)
[See Section 5.2 for condensed version; full 50-app matrix available in market-research-report.md]
---
### Appendix D: Technical Architecture Diagrams
[Detailed architecture diagrams to be created during technical design phase]
---
### Appendix E: User Journey Maps
[User journey maps for each persona to be created during design phase]
---
### Appendix F: Wireframes and Mockups
[To be created during design phase; references: Forest, Session, Finch for inspiration]
---
## Document Approval
| Role | Name | Signature | Date |
|------|------|-----------|------|
| Product Lead | | | |
| Engineering Lead | | | |
| Design Lead | | | |
| ADHD Advisor | | | |
---
**Next Steps:**
1. Review and approve PRD
2. Create detailed technical specification
3. Begin MVP development
4. Recruit beta testers from ADHD communities
5. Plan Product Hunt launch
---
*This PRD is a living document. Update as new research and user feedback becomes available.*

0
docs/PRD.md → docs/PRD/PRD.md
View File

0
docs/gamify-glm51.md → docs/study/gamify-glm51.md
View File

0
docs/gamify-minimax-m2.7.md → docs/study/gamify-minimax-m2.7.md
View File

0
docs/gamify-qwen3.5.md → docs/study/gamify-qwen3.5.md
View File

0
docs/market-research-glm51.md → docs/study/market-research-glm51.md
View File

0
docs/market-research-llama.md → docs/study/market-research-llama.md
View File

0
docs/market-research-report.md → docs/study/market-research-report.md
View File

0
docs/study-glm51.md → docs/study/study-glm51.md
View File

0
docs/study-minimax-m2.7.md → docs/study/study-minimax-m2.7.md
View File

0
docs/study-qwen35.md → docs/study/study-qwen35.md
View File