Summary
The Behavioral Coaching Logic acts as a smart assistant that helps users build better digital habits without feeling overwhelmed. Instead of just blocking apps, it analyzes usage patterns over time to offer personalized suggestions—like slightly lowering a limit when a user is doing well, or offering a “recovery” buffer if they are constantly struggling. It also manages the “Snooze” system, which adds progressive friction to prevent mindless bypassing of limits.How It Works
The coaching system operates in a continuous loop of observation, analysis, and intervention.The Gatekeeper (Timing)
Before calculating anything, the Coach Suggestion Manager checks if it is appropriate to speak to the user. It ensures the app doesn’t become annoying by enforcing rules like:
- Cooldowns: Don’t show a suggestion if the user saw one in the last 24 hours.
- Snoozing: If a user clicked “Snooze for 7 days,” the coach stays silent until that date.
- Hysteresis: If the user just changed their limit, wait a week before suggesting another change to let the new habit settle.
Analyzing Performance (The Phases)
If the gatekeeper allows it, the Coach Service looks at the user’s recent history. It applies different logic based on how long the user has been using the app:
- Phase 1 (New User): Compares today’s usage against the last few days. It offers tiny nudges to fix immediate issues.
- Phase 2 (Settling In): Compares the last week against the overall average. It looks for trends, like whether weekends are significantly different from weekdays.
- Phase 3 (Veteran): Uses advanced statistics. It ignores “freak” days (outliers) to find the user’s true baseline and suggests robust changes.
Generating the Proposal
Based on the analysis, the Smart Limit Policy calculates specific numbers. It typically offers three paths:
- Maintain: Keep the current limit (validating good behavior).
- Easy Goal: A small reduction (e.g., 10%) that feels achievable.
- Ambitious Goal: A larger reduction (e.g., 30%) for users who want a challenge.
Managing Friction (The Snooze System)
When a user hits their limit and tries to bypass it, the Snooze Manager uses an Exponential Strategy. It makes snoozing progressively harder throughout the day:
- Compassion Phase: The first 1-2 snoozes are easy and grant generous time (e.g., 15 mins).
- Reflection Phase: The next few attempts grant less time (e.g., 5 mins) and force a short waiting period (cooldown) before the app unlocks.
- Deliberate Phase: Subsequent attempts grant very little time, require a long wait, and ask reflection questions like “Is this aligned with your goals?”
Data Stored
The coaching logic persists specific metadata to manage timing and history.| Field | Type | Description |
|---|---|---|
last_applied_date | String | The date the user last accepted a coach suggestion. |
snoozed_until | String | A future date until which the coach should remain silent. |
last_notified_timestamp | Long | The exact time the last notification was shown (for 24h cooldowns). |
snooze_history | List | A record of how many times a user snoozed a limit today, used to calculate friction. |
Key Components
Coach Suggestion Manager
The “Gatekeeper” that decides when to show a suggestion, ensuring the app respects user snoozes and prevents notification spam.
Coach Suggestion Service
The “Brain” that decides what to suggest by analyzing usage history, detecting weekend patterns, and identifying burnout.
Smart Limit Policy
The “Mathematician” that calculates the specific minute values for suggestions (e.g., rounding to the nearest 5 minutes).
Snooze Strategy
The “Enforcer” that manages the progressive friction system, making it harder to bypass limits the more often a user tries.