From cdf1e5eaa42a0dc40350d28d714a1e2c6b46f9b8 Mon Sep 17 00:00:00 2001 From: stellarshenson Date: Sun, 25 Jan 2026 11:51:20 +0100 Subject: [PATCH] docs: add rationale for 72-hour half-life choice Explains why 72h calendar half-life was chosen: - Decay applies to wall-clock time, not working time - Users work ~8h/day (1/3 of 24h period) - 72h calendar = ~24h of working time = one full workday - Prevents overnight breaks from penalizing scores This calibrates decay to actual engagement patterns rather than raw calendar time. --- .claude/JOURNAL.md | 2 +- docs/activity-tracking-methodology.md | 16 ++++++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/.claude/JOURNAL.md b/.claude/JOURNAL.md index 131e329..c64a9c6 100644 --- a/.claude/JOURNAL.md +++ b/.claude/JOURNAL.md @@ -251,4 +251,4 @@ This journal tracks substantive work on documents, diagrams, and documentation c **Result**: Changed Activity column header from "Activity (7 days)" to just "Activity" in activity.html 83. **Task - Activity monitor half-life to 72h (3 days)**: Extended decay half-life for smoother scoring
- **Result**: Updated JUPYTERHUB_ACTIVITYMON_HALF_LIFE default from 48h to 72h across Dockerfile, custom_handlers.py, activity_sampler.py, settings_dictionary.yml, README.md, and docs/activity-tracking-methodology.md. With 72h half-life, activity from 3 days ago has 50% weight, providing more stable activity scores for users with irregular schedules + **Result**: Updated JUPYTERHUB_ACTIVITYMON_HALF_LIFE default from 48h to 72h across Dockerfile, custom_handlers.py, activity_sampler.py, settings_dictionary.yml, README.md, and docs/activity-tracking-methodology.md. Added rationale section explaining why 72h: decay applies to wall-clock time, not working time. A user working 8h/day is active only 1/3 of each 24h period - with 72h calendar half-life, ~24 working hours (3 days × 8h) have 50% weight, effectively calibrating decay to one full workday of engagement. This prevents overnight breaks from aggressively penalizing scores diff --git a/docs/activity-tracking-methodology.md b/docs/activity-tracking-methodology.md index 3205ed0..c7ee1bc 100644 --- a/docs/activity-tracking-methodology.md +++ b/docs/activity-tracking-methodology.md @@ -9,6 +9,22 @@ Our current approach uses **exponential decay scoring**: - Weight formula: `weight = exp(-λ × age_hours)` where `λ = ln(2) / half_life` - Default half-life: 72 hours / 3 days (activity from 3 days ago worth 50%) +### Why 72-hour Half-life? + +The decay applies to **wall-clock time**, not working time. A typical user works 8-9 hours per day - roughly 1/3 of a 24-hour period. This creates a mismatch between calendar decay and effective working activity decay: + +| Calendar Half-life | Working Hours in Period | Effective Work Half-life | +|--------------------|-------------------------|--------------------------| +| 24 hours | ~8 hours | ~8 hours of work | +| 72 hours (3 days) | ~24 hours | ~24 hours of work | + +With a 72-hour calendar half-life: +- A user working 8h/day accumulates ~24 hours of working time over 3 calendar days +- Activity from those 24 working hours has 50% weight +- The decay is effectively calibrated to **one full workday** of actual engagement + +This makes scores more stable for users with typical work patterns. A 24-hour half-life would be too aggressive - yesterday's full workday would already be at 50% weight before today even starts, penalizing normal overnight breaks + ## Industry Approaches ### 1. Exponential Moving Average (EMA) / Time-Decay Systems