usage_drop_diagnosis v1.0.0

name: usage_drop_diagnosis description: "Diagnose a drop in product usage from raw usage exports: freeze the metric definition, segment the drop first, decompose who accounts for the fall, match the shape and pattern to likely causes, rule out measurement and seasonality, and decide outreach from evidence. Use when DAU, WAU, MAU, sessions, or a core action count falls and someone asks why, or before any win-back or incident response based on a usage chart."

Usage Drop Diagnosis

Purpose

Find out what actually fell, where it fell, and what to do next, starting from a raw export instead of a health dashboard. Most usage panics go wrong in the first hour: someone reads the aggregate line, guesses a cause, and sends a broad win-back or rolls back a release that had nothing to do with it. The aggregate line is the worst place to start. A total can fall because one segment broke, because every segment fell a little, because the mix shifted toward a low-use segment, or because the tracking broke. Each cause has a different fix and a different outreach rule.

This skill works without dedicated health tooling. All it needs is a daily export with a date, a segment, and a count.

Workflow

1. Freeze the metric before you measure the drop. Write down, on the report:

• The activity event that counts as use. One event, named exactly as it appears in the data. A login, an app open, and a core action are three different metrics.
• The unit: unique users, sessions, or events. Never trend across a unit change.
• The window rule: calendar day in which timezone, and whether today is complete. An in-progress day is not a drop.
• The segment columns available in the export: platform, plan, country, acquisition source, new vs returning, app version, or whatever the export carries. If the definition changed inside the window, split the report at the change date. A definition change explains a step on its own until proven otherwise.

1. Prove the drop is real before you explain it. Run these checks in order and record each result:

• Partial window: drop the final incomplete day. The bundled tool does this with --partial-last-day.
• Completeness: every segment present on every date, no duplicate date plus segment rows, no zero days that used to be impossible. A missing segment day is a data gap first, a user fall second.
• Denominator check for rates: if a rate fell, check whether the numerator fell, the denominator grew, or both. A rate can fall with flat usage when a large low-rate group arrives.
• Instrumentation check: did a release, SDK update, consent change, or tracking edit land on the onset date? If event volume fell on every platform at the same hour while server-side counts held, suspect capture, not users.
• Experiment check: if a running experiment covers the affected segment, compare exposed vs unexposed before blaming the product. If any check fails, the finding is a measurement problem. Fix that first and say so plainly.

1. Segment first, then read the total. Run the bundled tool on the export: python3 scripts/diagnose.py usage.csv --md diagnosis.md Default windows are the last 7 days against the 7 days before them. Two consecutive 7 day windows each contain every weekday once, so the comparison is weekday matched by construction. For longer or shorter history, pass explicit --baseline-start, --baseline-end, --drop-start, and --drop-end dates, and keep both windows the same length and a multiple of 7 days where the data allows. Read the output in this order: total change, segment contribution table, breadth, shape. Do not write a cause sentence until all four are on the page.

1. Decompose the fall. Contribution answers who accounts for the drop, in a way percent change alone cannot:

• Contribution of a segment = (baseline daily mean minus drop daily mean for that segment) divided by (baseline daily mean minus drop daily mean in total), times 100.
• A small segment can fall 50 percent and account for almost none of the total fall. A large segment falling 5 percent can account for most of it. Rank work by contribution, not by percent change.
• Segments under the low volume floor (default baseline mean under 10 per day) get flagged and pooled. A handful of users moving is noise, not a pattern.
• For rate metrics, run the mix vs within-segment split in references/rate-decomposition.md. An aggregate rate can fall while every segment rate holds, purely because the mix shifted. That is the mix effect, and it is not a product break.

1. Match the pattern to a short cause list. Use references/pattern-table.md. The main patterns:

• Concentrated: one segment accounts for at least half the fall and most segments did not fall materially. Start with that segment: its version, its release, its platform policy, its top accounts.
• Broad: at least 70 percent of material segments fell materially. Start with shared causes: release, incident, outage, pricing or policy change, external event.
• New users only: acquisition or activation fell, returning users held. Start with signup flow, campaigns, store listing, and first-session value.
• Returning users only: the base eroded while new intake held. Start with habit breaks, content or value running out, and competing changes in users' routines.
• Shape adds timing: a cliff points at a dated event, a gradual slope points at erosion or a slow external shift, a transient dip that recovers points at an outage, holiday, or weather style event and usually needs no outreach at all. Treat every matched cause as a hypothesis with a named test, not as a finding. The test is the next step in the pattern table.

1. Check the calendar honestly. Before calling anything a trend:

• Compare same weekdays. Monday against Monday, never Monday against the weekend for a work product, or the reverse for a consumer product.
• Compare the same period last year or last cycle when the product is seasonal, and say when no prior cycle exists.
• List holidays, school breaks, paydays, and known external events inside both windows when they plausibly move this product's use. List them as context, not as an excuse. A holiday explains a dip only if the dip matches its dates and reverses after it.
• Check releases, incidents, price changes, and campaigns against the onset date, not against the date someone noticed the chart.

1. Decide outreach from the pattern, not from the size of the panic. Full rules in references/outreach-rules.md. The short version:

• Concentrated drop with a named broken thing: contact only the affected segment, name the problem and the fix, and skip everyone else.
• Broad drop with a confirmed product cause: one clear notice to affected users, with status and workaround if one exists.
• Cause unknown: no win-back, no discount, no apology blast. Run the tests from step 5 first. Contacting users about a drop you cannot explain trains them to ignore you and burns the one good outreach you get.
• Transient dip that already recovered: no outreach. Record it and move on.
• Measurement problem: no user outreach at all. Fix the tracking and restate the numbers.

1. Write the diagnosis. Follow the Output Contract. Every cause claim gets a label: confirmed (a test or a server-side count proves it), likely (pattern plus a dated event line up, test still pending), or unknown (pattern described, cause not yet tested). Never upgrade a likely to a confirmed in the summary line.

Output Contract

• Header: metric definition (event, unit, timezone, window rule), baseline window, drop window, export source and date range.
• Reality checks: partial window, completeness, denominator, instrumentation, and experiment results, each pass, fail, or not checked with a reason.
• Headline numbers: baseline daily mean, drop daily mean, total percent change.
• Segment table: segment, baseline per day, drop per day, own percent change, share of the total fall, low volume flag.
• Pattern and shape: one of concentrated, broad, mixed, new only, returning only, or no drop, plus cliff, gradual, transient, or sustained, with the numbers that support the call.
• Cause list: each cause labelled confirmed, likely, or unknown, with the test that would confirm or rule it out and who runs it.
• Calendar context: weekday matching method, seasonal comparison used or its absence, dated events inside the windows.
• Outreach decision: who gets contacted, with what message, or an explicit no-outreach call with the reason.
• Limits: missing segments, gaps, small segments, and any definition change inside the window.
• Worked example: references/worked-example.md, with the sample data in assets/sample-usage.csv and the exact tool output it produces.

Operating Rules

1. Segment before you explain. Any cause sentence written from the aggregate line alone gets deleted and rewritten after the segment table exists.
2. Rank by contribution, not by percent change. Percent change decides how a segment feels. Contribution decides where the work goes.
3. Never score a partial window, and never compare mismatched weekdays without saying so on the report.
4. A drop in a rate is two questions: what happened to the numerator, and what happened to the denominator. Answer both.
5. Mix shift is not a product break. If every segment held and only the mix moved, the report says mix shift and the action sits with acquisition or onboarding, not with the product team on call.
6. Thresholds in this skill (half the fall in one segment, 70 percent breadth, 5 percent material fall, 10 percent recovery band) are starting rules. Calibrate them to the product's normal weekly swing and record the change when you do.
7. No outreach without a pattern and a cause label. Unknown cause means research next step, not a campaign.
8. Keep the diagnosis reproducible: same export, same windows, same result. Save the export, the command, and the output with the report.
9. Follow the style law: no em dashes, plain direct language, no press release phrasing.