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