← All craftbooks

Cohort / Retention Analysis

Data and analysisevalv1.0.0released 2026-06-05workflow: build-loop

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

1. Scope the cohortsdata-analystentry

   lock the cohort key, activity event, and retention window

   Show working prompt

   Define retention unambiguously before computing anything. Step 1: choose the cohort key — usually signup/first-activity period (weekly or monthly), and state the period. Step 2: define the ACTIVITY that counts as 'retained' (logged in, made a purchase, used core feature) and the unit (a user, an account). Step 3: define the retention window and periods (W0..W8, or M0..M6) and whether it's classic (active in period N) or rolling/unbounded. Step 4: state filters (exclude test accounts, a minimum-tenure cutoff so incomplete recent cohorts are flagged). Step 5: write an acceptance-criteria checklist ('cohort key and activity are precisely defined', 'retention table has cohorts as rows and periods as columns', 'period 0 is 100% by construction', 'incomplete recent cohorts are flagged', 'a trend across cohorts is reported'). Call write_task_note and write the definitions + checklist to notes/scope.md.

2. Build the cohort tabledata-analyst

   compute the retention matrix and curves

   Show working prompt

   Compute the cohort retention matrix from the defined rules. Step 1: assign each user/account to its cohort by the cohort key. Step 2: for each cohort and each retention period, compute the share of the cohort that performed the activity in that period; period 0 is 100% by construction. Step 3: build the triangular retention matrix (cohorts x periods), the cohort sizes, and the average retention curve across cohorts. Step 4: compute the trend — are later cohorts retaining better at the same period age than earlier ones? Step 5: flag cohorts too recent to have full data. Emit data/cohorts.json (matrix, sizes, average curve, trend) and call write_task_note with the headline retention numbers and the trend.

3. Write the readoutcopywriter

   explain what the cohorts reveal about retention

   Show working prompt

   Write the retention readout from the computed matrix — no invented figures. Step 1: lead with the headline: the typical W1/M1 retention and where the curve flattens (the 'sticky' floor). Step 2: present the retention table (cohorts as rows, periods as columns) and read it for the reader. Step 3: state the cross-cohort trend in plain language ('M1 retention improved from 22% to 31% over the last 6 cohorts'). Step 4: call out the best and worst cohorts and any inflection. Step 5: caveat the incomplete recent cohorts and suggest one next action. Write the readout to readout.md and call write_task_note with the path. On a loop-back, fix only the named gaps.

4. Evaluatereviewer

   Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

   Show working prompt

   Read readout.md and cross-check against notes/scope.md and data/cohorts.json. Verify: the cohort key and activity are precisely defined and used; the retention table has cohorts as rows and periods as columns with period 0 = 100%; incomplete recent cohorts are flagged; and a cross-cohort trend is reported with numbers. Re-check the headline W1/M1 retention and the trend against the cohort data. Confirm no cohort's retention exceeds 100% or rises impossibly. Write PASS/FAIL per criterion; any FAIL loops back to write.
   
   Then route — this is the whole point of the loop:
   
   - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
   - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "write" })` to loop back. The builder fixes exactly those gaps.
   
   Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.

5. Finishdeveloper

   All acceptance criteria met. Stamp a short summary and report DONE.

   Show working prompt

   Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

• cohort analysis
• retention curve
• are newer users retaining better
• churn analysis
• retention table

Source

View this craftbook on GitHub · MIT license