When to use

• A stakeholder asks "are we retaining users better than last quarter?"
• You need to measure N-day, weekly, or monthly retention for a product or feature
• You want to compare how different acquisition cohorts (by channel, plan, or signup date) perform over their lifetime
• You're investigating churn and need to identify at which period users typically leave

Process

1. Define the cohort and activity, clarify: cohort grouping (signup month, first purchase date, etc.) and retention event (login, purchase, feature use). Document in the report header.
2. Pull or build the data, if starting from a database, use scripts/cohort_query.sql as the starting point. Adapt the cohort_date and activity_date columns to your schema.
3. Build the cohort table, run scripts/cohort_builder.py to produce a cohort × period membership table from event data. Output is a CSV with user_id, cohort_period, activity_period.
4. Compute the retention matrix, run scripts/retention_matrix.py on the cohort table to generate the period-over-period retention rates. Output is an N×M matrix (cohort × period).
5. Visualise, run scripts/cohort_visualizer.py to render a heatmap of the retention matrix and a time-series of retention curves per cohort.
6. Interpret findings, consult references/retention_metrics_glossary.md for metric definitions and references/cohort_definition_patterns.md for pattern recognition.
7. Write the report, fill assets/cohort_report_template.md. For a visual deliverable, fill in the assets/retention_matrix.html heatmap template.