---
name: analyze-metrics
description: Analyze product metrics and identify trends when the user asks to review metrics, analyze KPIs, or assess product health
author: chalk
version: "1.0.0"
metadata-version: "3"
allowed-tools: Read, Glob, Grep, Write
argument-hint: "[metric name, period, or metrics file]"
read-only: false
destructive: false
idempotent: false
open-world: false
user-invocable: true
tags: analysis, metrics, data
---

# Analyze Metrics

## Overview

Review product metrics against targets, identify trends across cohorts, distinguish leading from lagging indicators, and generate hypotheses for unexpected changes. Turns raw numbers into actionable insight.

## Workflow

1. **Read metrics context** — Scan `.chalk/docs/product/` for any metrics framework, KPI definitions, or previous metrics reviews. Identify which metrics have defined targets and baselines.

2. **Gather metrics data** — Parse `$ARGUMENTS` for the specific metrics or period to analyze. If the user provides data inline or references a file, read it. If no data is provided, ask the user to supply current metric values.

3. **Classify each metric** — For each metric, determine:
   - Type: leading (predictive) vs. lagging (outcome)
   - Category: acquisition, activation, engagement, retention, revenue, referral
   - Comparison basis: target value, previous period, cohort benchmark

4. **Assess current vs. target** — Compare each metric's current value against its target. Classify as: on-track (within 10%), at-risk (10-25% off), or off-track (>25% off). If no target exists, note the gap.

5. **Identify trends** — For each metric with historical data, classify the trend: improving, stable, or declining. Note acceleration or deceleration (is improvement slowing down?). Flag inflection points.

6. **Cohort comparison** — Where cohort data is available, compare across user segments (new vs. returning, plan tiers, acquisition channels). Identify cohorts that outperform or underperform the average.

7. **Generate hypotheses** — For any metric that is off-track or shows unexpected changes, propose 2-3 hypotheses for the cause. Each hypothesis should be testable. Connect to recent product changes, market events, or seasonal patterns.

8. **Identify metric relationships** — Flag leading indicators that predict lagging indicator changes. Note correlations and potential causal chains.

9. **Determine the next file number** — Read filenames in `.chalk/docs/product/` to find the highest numbered file. Use `highest + 1`.

10. **Write the review** — Save to `.chalk/docs/product/<n>_metrics_review_<period>.md`.

## Output

- **File**: `.chalk/docs/product/<n>_metrics_review_<period>.md`
- **Format**: Markdown with a health dashboard table and detailed metric sections
- **Key sections**: Health Summary Table (metric / current / target / status / trend), Detailed Analysis per metric, Cohort Insights, Hypotheses for Off-Track Metrics, Recommended Actions

## Anti-patterns

- **Vanity metrics without context** — Reporting "10K signups" without conversion rate, activation rate, or retention is misleading. Always pair volume metrics with quality metrics.
- **Confusing correlation with causation** — "We launched feature X and signups went up" is a correlation, not a causal claim. Always note confounders and suggest experiments to validate.
- **Ignoring leading indicators** — Only reviewing lagging indicators (revenue, churn) means you are looking in the rearview mirror. Prioritize leading indicators that let you act before outcomes materialize.
- **Reporting without hypotheses** — Stating "retention dropped 5%" without proposing why is not analysis. Every unexpected change needs at least one testable hypothesis.
- **Missing cohort breakdowns** — Aggregate metrics hide important variation. A stable overall retention rate can mask declining retention in new cohorts offset by strong retention in old cohorts.