Session Cancellation Flow - RegardingWork Game

👤 User Experience Flow

🎯 Current Behavior (What Users See)

User clicks "Cancel Session"
During an active 25-minute timer session
❌ Stop
Timer immediately ends
Session stops counting, no more timing
⏹️ End
Cancellation Log Screen
Shows session summary + reason collection
📝 Log
Optional Details Entry
Reason dropdown + optional detailed notes
💭 Note
API Call to Database
Records cancellation + sends Slack notification
💾 Save
Cancellation Receipt
Shows partial POF points earned + summary
🧾 Done

✅ What Users Get

Partial POF Points: Based on completion percentage
Team Notification: Slack alert about cancellation
Analytics Tracking: Cancellation patterns recorded
Profile Activity: Shows in activity timeline
Self-Reflection: Understanding interruption patterns

🔧 Technical Implementation

📡 API Endpoint

POST /api/session/cancel
Requires JWT authentication

Required Fields:

session_id - UUID of original session
planned_duration - Original minutes planned
elapsed_minutes - Actual time completed

Optional Fields:

reason - Cancellation category
cancel_reason_note - User's detailed explanation
category - Original work category
project_id / team_project_id - Project links

💾 Database Storage

Table: session_cancellation

Key Data Points:

📊 Partial POF Score: Calculated completion percentage
⏱️ Duration Data: Planned vs actual minutes
🏷️ Categorization: Reason + detailed notes
📱 Source Tracking: App version, browser, endpoint
👥 Project Links: Personal or team project associations
⏰ Timestamp: Exact cancellation time (UTC)

🛠️ Developer Instructions

📋 Implementation Checklist for Mac/Windows Agents

🎯 Cancel Button Handler

User clicks "Cancel Session" → Confirmation dialog appears
Point of No Return: User confirms → Session 100% cancelled via API immediately
Timer stops, Slack notification sent, partial POF awarded
Optional details screen shown (cancellation already recorded)
User can add reason + detailed notes OR skip to receipt
Receipt shows partial POF points and cancellation summary

🚫 Remove Confirmation Popups

❌ No "Are you sure?" dialogs
❌ No "Skip adding execution notes?" popups
❌ No confirmation after 4 minutes
✅ Auto-submit when timer completes
✅ Direct to API endpoint after 4 minutes

🔥 Critical Implementation Notes

Wrong Behavior: Cancel → Back to session planning form
Correct Behavior: Cancel → Confirm Dialog → Immediate API call → Optional details → Receipt
Point of No Return: Once user confirms cancellation, session is 100% cancelled (no going back)
Optional Details: User can add notes OR skip - cancellation already recorded either way
Timer Complete: Auto-submit to /api/pomodoro/submit (no confirmation popups)

📈 Analytics & Insights

🎯 Individual Insights

Cancellation patterns by time of day
Common interruption sources
Project types with higher cancel rates
Completion percentage trends
Partial POF score progression

👥 Team Analytics

Team-wide cancellation rates
Project-specific interruption data
Cross-platform completion patterns
Peak interruption time analysis
Focus improvement recommendations

🔍 Business Intelligence

Mac vs Windows vs Web cancellation rates
App version performance metrics
Feature adoption tracking
User engagement optimization
Platform reliability insights

🔧 Troubleshooting

Common Issues & Solutions

Cause: App is not calling /api/session/cancel endpoint
Solution: Verify the cancellation API call is implemented in cancel button handler
Test: Check session_cancellation table for new records

Cause: Wrong navigation flow implemented
Solution: Cancel → Cancellation log screen → API call → Receipt
Reference: Web implementation at /timer/cancel/[session_id]

Cause: Legacy confirmation dialogs still enabled
Solution: Remove all timer completion confirmations
Flow: Timer ends → Auto-submit to /api/pomodoro/submit

⚠️ Session Cancellation Flow