/metrics-track

Set up a metrics tracking plan for a project. Defines PostHog event funnel, KPI benchmarks, and kill/iterate/scale decision thresholds based on lean startup principles.

# /metrics-track

Set up a metrics tracking plan for a project. Defines PostHog event funnel, KPI benchmarks, and kill/iterate/scale decision thresholds based on lean startup principles.

## MCP Tools (use if available)

- `kb_search(query)` — find PostHog methodology, analytics patterns

If MCP tools are not available, fall back to Grep + Read.

## Methodology Reference

This skill implements metrics tracking based on lean startup principles:
- **Relative metrics vs niche benchmarks** — compare against your own trajectory, not vanity averages
- **Kill/iterate/scale decision rules** — data-driven thresholds for product decisions (see step 7 below)

## Steps

1. **Parse project** from `$ARGUMENTS`.
   - Read PRD for features, ICP, monetization model.
   - Read CLAUDE.md for stack (iOS/Web/both).
   - If empty: ask via AskUserQuestion.

2. **Detect platform:**
   - iOS app → PostHog iOS SDK events
   - Web app → PostHog JS SDK events
   - Both → cross-platform identity (shared user ID across platforms)

3. **Load PostHog methodology:**
   - If MCP available: `kb_search("PostHog analytics events funnel identity")`
   - Otherwise: check project docs for existing analytics configuration
   - Extract: event naming conventions, identity resolution, funnel pattern

4. **Define event funnel** based on PRD features:

   Standard funnel: `Awareness → Acquisition → Activation → Revenue → Retention → Referral`

   See `references/kpi-benchmarks.md` for the full event table, KPI thresholds, PostHog code snippets, and A/B test template. Adapt events to the specific product.

5. **Forced reasoning — metrics selection:**
   Before defining KPIs, write out:
   - **North Star Metric:** The ONE number that matters most (e.g., "weekly active users who completed core action")
   - **Leading indicators:** What predicts the North Star? (e.g., "activation rate D1")
   - **Lagging indicators:** What confirms success? (e.g., "MRR", "retention D30")
   - **Vanity metrics to AVOID:** (e.g., total downloads without activation)

6. **Set KPI benchmarks** per stage:

   Use thresholds from `references/kpi-benchmarks.md` as starting point. Adjust for product type (B2B has lower volume/higher conversion, B2C mobile has higher volume/lower retention).

7. **Define decision rules** — use kill/iterate/scale framework from `references/kpi-benchmarks.md`. Adapt thresholds to project-specific values from step 6.

8. **Generate PostHog implementation snippets** — use platform-specific examples from `references/kpi-benchmarks.md`. Adapt event names and properties to the funnel defined in step 4.

9. **A/B Test Analysis Template** — copy template from `references/kpi-benchmarks.md` into the metrics plan. Include decision rules (SHIP / KEEP / EXTEND / INCONCLUSIVE).

10. **Write metrics plan** to `docs/metrics-plan.md`:

   ```markdown
   # Metrics Plan: {Project Name}

   **Generated:** {YYYY-MM-DD}
   **Platform:** {iOS / Web / Both}
   **North Star:** {north star metric}

   ## Event Funnel

   | Stage | Event | Properties |
   |-------|-------|------------|
   {event table from step 4}

   ## KPIs & Thresholds

   | KPI | Target | Kill | Scale |
   |-----|--------|------|-------|
   {benchmark table from step 6}

   ## Decision Rules

   {framework from step 7}

   ## Implementation

   ### PostHog Setup
   - Project: {project name} (EU region)
   - SDK: {posthog-ios / posthog-js}
   - Identity: {anonymous → identified on signup}

   ### Code Snippets
   {snippets from step 8}

   ## A/B Test Template
   {template from step 9}

   ## Dashboard Template
   - Funnel: {stage1} → {stage2} → ... → {stageN}
   - Retention: D1 / D7 / D30 cohort chart
   - Revenue: MRR trend + trial conversion

   ---
   *Generated by /metrics-track. Implement events, then review weekly.*
   ```

11. **Output summary** — North Star metric, key thresholds, first event to implement, A/B template included.

## Notes

- PostHog EU hosting for privacy compliance
- Use `$set` for user properties, `capture` for events
- Identity: start anonymous, `identify()` on signup with user ID
- Cross-platform: same PostHog project, same user ID → unified journey
- Review dashboard weekly, make kill/iterate/scale decision monthly

## Common Issues

### Wrong platform detected
**Cause:** Project has both web and iOS indicators.
**Fix:** Skill checks package manifests. If both exist, it generates cross-platform identity setup. Verify the detected platform in the output.

### KPI thresholds too aggressive
**Cause:** Default thresholds are industry averages.
**Fix:** Adjust thresholds in `docs/metrics-plan.md` based on your niche. B2B typically has lower volume but higher conversion.

### PostHog SDK not in project
**Cause:** Metrics plan generated but SDK not installed.
**Fix:** This skill generates the PLAN only. Install PostHog SDK separately: `pnpm add posthog-js` (web) or add `posthog-ios` via SPM (iOS).