| name | analyze-user-behavior |
| description | Analyze event-level user or product-usage data and turn it into defensible metrics, diagnostics, and product recommendations. Use for CSV, JSON, or JSONL datasets and requests involving active users, new users, activation, DAU/WAU/MAU, retention, cohorts, usage frequency, funnels, feature adoption, segment comparison, churn or reactivation investigation, weekly/monthly user analytics, or evidence-backed product reports. Also use when the user asks why a user metric changed or what product action the data supports. |
Analyze User Behavior
Produce trustworthy user analytics by separating deterministic measurement from model-led interpretation. Calculate metrics with the bundled script when the source is event-level; use the same contracts manually for aggregate sources.
Workflow
- Define the decision, audience, time window, comparison, and unit of analysis. Distinguish users, accounts, sessions, tasks, devices, and events before calculating anything.
- Read data-contract.md before using a new source. Map columns explicitly and identify whether registration, activation, session, segment, and feature events are observable.
- Read metric-definitions.md before selecting metrics or interpreting results. State any definition that differs from the defaults.
- For event-level CSV, JSON, or JSONL, run
scripts/analyze_events.py. Do not ask the model to recalculate values already produced by the script.
- Review
quality, denominators, observation coverage, and incomplete-period warnings before interpreting results. Stop or narrow claims when missing data could change the answer.
- Diagnose the smallest set of actionable cuts. Separate verified facts, likely explanations, and unresolved hypotheses. Do not convert correlation into causation.
- When producing a durable report, read report-contract.md, build the answer-first narrative, and preserve the analysis JSON as supporting evidence.
- Hand off the result with the controlling definitions, source limitations, output paths, and the next decision or experiment the evidence supports.
Run Event Analysis
Use Python 3.10+ and the standard library only:
python3 scripts/analyze_events.py events.csv \
--user-column user_id \
--timestamp-column event_time \
--event-column event_name \
--session-column session_id \
--segment-column plan \
--activation-events onboarding_completed,first_value \
--funnel signup,onboarding_completed,first_value \
--period-days 7 \
--output user_analysis.json
Accept .csv, .json arrays, .jsonl, and .ndjson. For Excel, export the relevant sheet to CSV rather than adding a runtime dependency. Omit optional column or event arguments when the source does not contain them.
Use --complete-through YYYY-MM-DD only when the user or source confirms that date is complete. Otherwise treat the latest observed day as potentially partial. Use --dedupe only when the event identity rule makes exact duplicates invalid.
Run the built-in check after modifying the script:
python3 scripts/analyze_events.py --self-test
Trust Rules
- Never silently treat first observed activity as registration. Label it
first seen unless a registration event or user table controls the definition.
- Never mix grains in one denominator. In particular, do not count tasks, sessions, or devices as users.
- Never hide unknown, missing, immature, or censored populations when they could change the conclusion.
- Never expose raw identifiers or personal data in the report. Aggregate small segments or omit them.
- Never call a segment difference causal without an experiment or a credible causal design.
- Never recommend a product action without naming the evidence, uncertainty, expected mechanism, and measurement plan.
Output Modes
- Answer a single bounded metric lookup inline after validating its definition and denominator.
- Produce a report for trends, comparisons, funnels, retention, segment cuts, diagnostics, or recommendations.
- Prefer one decision-ready report plus one machine-readable analysis artifact. Create extra spreadsheets, slides, or dashboards only when requested.
