surge/docs/features.md

Feature Definition: Surge

Executive Summary

Surge is a mobile application designed to help users discover, track, and complete structured self-improvement challenges. This feature definition establishes the core functionality required for MVP launch, focusing on the challenge library and personal progress tracking systems that form the foundation of the user experience.

The MVP prioritizes delivering immediate value to fitness enthusiasts and habit builders by solving their primary pain point: staying organized and accountable during demanding multi-day challenges. Social features are intentionally deferred to post-MVP phases.

---

User Personas & Scenarios

Primary Personas

The Committed Challenger (Primary)

• Demographics: 25-40 years old, fitness-oriented
• Goals: Complete demanding challenges like 75 Hard without losing track
• Pain Points: Currently uses spreadsheets or notes apps, loses momentum mid-challenge
• Behavior: Checks progress daily, motivated by streaks and visual progress

The Habit Explorer (Secondary)

• Demographics: 20-35 years old, self-improvement focused
• Goals: Discover and try various challenge formats to build better habits
• Pain Points: Doesn't know which challenges exist or which suit their goals
• Behavior: Browses options before committing, prefers shorter challenges initially

Key User Scenarios

Scenario 1: Starting a New Challenge Sarah discovers Surge after deciding to attempt 75 Hard. She browses the challenge library, reads the specific requirements (two workouts, diet adherence, water intake, reading, progress photo), and starts the challenge with a clear understanding of daily expectations.

Scenario 2: Daily Check-in Routine Marcus is on Day 23 of his challenge. Each evening, he opens Surge, checks off completed tasks for the day, sees his streak count increase, and views his progress visualization showing he's 30% complete.

Scenario 3: Recovery from Missed Day Elena missed a requirement on Day 15 of 75 Hard (the challenge requires restarting on any failure). Surge clearly shows her the rule was broken, offers encouragement, and provides a simple path to restart with her history preserved.

---

Feature Specifications

Feature 1: Challenge Library

Purpose: Provide users access to a curated collection of structured challenges with clear rules and requirements.

User Value: Users no longer need to research challenge rules across multiple sources—everything is centralized and clearly explained.

Functional Requirements

ID	Requirement	Priority
CL-01	Display browsable list of available challenges	Must Have
CL-02	Show challenge details: name, duration, description, difficulty	Must Have
CL-03	List specific daily requirements for each challenge	Must Have
CL-04	Filter challenges by duration and difficulty	Should Have
CL-05	Search challenges by name or keyword	Should Have
CL-06	Display challenge rules and failure conditions	Must Have
CL-07	Show estimated daily time commitment	Nice to Have

MVP Challenge Content

The library will launch with these challenges:

1. 75 Hard - 75 days, extreme difficulty
2. 75 Soft - 75 days, moderate difficulty
3. 30-Day Fitness Challenge - 30 days, moderate
4. 21-Day Meditation Challenge - 21 days, beginner
5. 30-Day No Sugar Challenge - 30 days, moderate

graph TD
    A[Challenge Library] --> B[Browse All]
    A --> C[Filter/Search]
    B --> D[Challenge Card]
    C --> D
    D --> E[Challenge Details]
    E --> F[View Requirements]
    E --> G[Start Challenge]
    G --> H[Active Challenge]

Acceptance Criteria

• User can view all available challenges within 2 seconds of opening library
• Each challenge displays duration, difficulty rating, and brief description on card
• Challenge detail view shows complete daily requirements list
• User can start any challenge with single tap from detail view

---

Feature 2: Personal Progress Tracking

Purpose: Enable users to track daily completion of challenge requirements and visualize their journey.

User Value: Replaces scattered tracking methods with a dedicated system that understands each challenge's specific structure.

Functional Requirements

ID	Requirement	Priority
PT-01	Display current day's required tasks as checkable items	Must Have
PT-02	Save daily completion status persistently	Must Have
PT-03	Show current streak count prominently	Must Have
PT-04	Display overall progress percentage/visualization	Must Have
PT-05	Track challenge start date and current day number	Must Have
PT-06	Handle challenge-specific failure rules	Must Have
PT-07	Allow viewing of past days' completion history	Should Have
PT-08	Send daily reminder notifications	Should Have
PT-09	Support multiple concurrent challenges	Nice to Have

Daily Check-in Flow

sequenceDiagram
    participant U as User
    participant A as App
    participant S as Storage

    U->>A: Open Daily View
    A->>S: Fetch today's requirements
    S-->>A: Return task list + status
    A-->>U: Display checkable tasks
    U->>A: Mark task complete
    A->>S: Update completion status
    A->>A: Recalculate streak/progress
    A-->>U: Update UI with new stats
    U->>A: Complete all tasks
    A-->>U: Show celebration + streak update

Progress Visualization

The progress dashboard displays:

• Current Day: "Day 23 of 75"
• Streak Counter: Consecutive days completed
• Progress Bar: Visual percentage complete
• Calendar View: Month view with completion indicators
• Today's Status: Remaining tasks for current day

Acceptance Criteria

• Daily tasks reflect the specific challenge's requirements
• Checking off tasks updates immediately with visual feedback
• Streak count updates upon completing all daily requirements
• Progress percentage calculates accurately based on days completed
• Past completion data persists across app sessions
• Failed challenges (per challenge rules) prompt restart option

---

Feature 3: Challenge Lifecycle Management

Purpose: Handle the complete journey from starting a challenge through completion or restart.

User Value: Clear guidance through challenge states reduces confusion and maintains motivation.

Challenge States

stateDiagram-v2
    [*] --> NotStarted: User views challenge
    NotStarted --> Active: Start Challenge
    Active --> Active: Daily completion
    Active --> Failed: Rule violation
    Active --> Completed: All days finished
    Failed --> Active: Restart
    Completed --> [*]: Challenge archived
    Failed --> NotStarted: Abandon

Functional Requirements

ID	Requirement	Priority
LM-01	Track challenge state (not started, active, failed, completed)	Must Have
LM-02	Display appropriate UI for each state	Must Have
LM-03	Provide restart functionality with attempt history	Should Have
LM-04	Show completion celebration on challenge finish	Should Have
LM-05	Archive completed challenges with final stats	Should Have

---

Feature 4: User Onboarding & Account

Purpose: Get users into the app quickly while enabling data persistence.

User Value: Minimal friction to start while ensuring progress is never lost.

Functional Requirements

ID	Requirement	Priority
UA-01	Email/password authentication	Must Have
UA-02	Social login (Apple, Google)	Should Have
UA-03	Brief onboarding highlighting key features	Should Have
UA-04	Profile with basic settings	Must Have
UA-05	Notification preferences management	Should Have

---

MVP Scope Definition

In Scope (MVP)

Category	Included
Challenge Library	5 curated challenges with complete requirements
Progress Tracking	Daily check-ins, streaks, progress visualization
Lifecycle	Start, track, complete, restart challenges
Account	Basic auth, profile, notification settings
Platform	iOS and Android via cross-platform framework

Out of Scope (Post-MVP)

Feature	Phase	Rationale
Social/Friends	Phase 2	Requires significant additional infrastructure
Leaderboards	Phase 2	Depends on user base for meaningful competition
Custom Challenges	Phase 2	Focus on curated quality first
Progress Photos	Phase 2	Storage and privacy considerations
Community Forums	Phase 3	Moderation requirements
Premium Subscriptions	Phase 2	Establish value before monetization

---

Success Metrics & KPIs

Primary Metrics

Metric	Target	Measurement
Day 7 Retention	>40%	Users returning 7 days after install
Challenge Start Rate	>60%	Users who start a challenge within first session
Daily Check-in Rate	>70%	Active challenge users checking in daily
Challenge Completion Rate	>15%	Users completing their started challenge

Secondary Metrics

Metric	Target	Measurement
App Store Rating	>4.5 stars	Average user rating
Session Duration	>2 min	Average time per session
Streak Length	>7 days avg	Average streak before break
Restart Rate	<50%	Users restarting after failure (lower = better initial success)

Tracking Implementation

graph LR
    A[User Actions] --> B[Analytics Events]
    B --> C[Challenge Started]
    B --> D[Daily Check-in]
    B --> E[Streak Milestone]
    B --> F[Challenge Completed]
    B --> G[Challenge Failed/Restart]
    C & D & E & F & G --> H[Dashboard]

---

User Flow Summary

graph TD
    A[App Launch] --> B{Authenticated?}
    B -->|No| C[Onboarding/Login]
    B -->|Yes| D{Active Challenge?}
    C --> D
    D -->|No| E[Challenge Library]
    D -->|Yes| F[Daily Dashboard]
    E --> G[Challenge Details]
    G --> H[Start Challenge]
    H --> F
    F --> I[Check Off Tasks]
    I --> J{All Complete?}
    J -->|Yes| K[Streak Updated]
    J -->|No| L[Pending Tasks]
    K --> M{Challenge Done?}
    M -->|Yes| N[Completion Screen]
    M -->|No| F

---

Technical Considerations

Data Requirements

• Challenge definitions (static, cacheable)
• User progress records (daily task completion)
• Streak calculations (derived from progress)
• User preferences and settings

Offline Capability

• Challenge content available offline after initial load
• Daily check-ins queue when offline, sync when connected
• Progress data cached locally with cloud backup

Notification Strategy

• Daily reminder at user-configured time
• Streak milestone celebrations (7, 14, 30, etc.)
• Gentle re-engagement after 2 days of inactivity

---

Recommendations

1. Prioritize Daily Experience: The check-in flow is the core interaction—invest heavily in making it fast, satisfying, and visually rewarding.
2. Nail the Streak Psychology: Streaks are the primary motivation mechanism. Consider streak freezes or recovery options for user retention.
3. Quality Over Quantity: Launch with 5 well-documented challenges rather than 20 incomplete ones. Each challenge should feel professionally curated.
4. Design for Failure Recovery: Most users will fail demanding challenges. The restart experience should feel encouraging, not punishing.
5. Build Analytics Foundation: Implement comprehensive event tracking from day one to inform Phase 2 social features.