Create Telemetry

---
name: create-telemetry
description: Define analytics events, success metrics, and telemetry for a feature so usage can be measured from day one.
argument-hint: "[specification-doc]"
---

# Create Telemetry

Defines how feature usage will be measured by identifying analytics events, success metrics, funnel steps, and telemetry requirements before implementation begins.

Without this step, features ship without instrumentation, making it impossible to measure adoption, diagnose issues, or base iteration decisions on data.

## Prerequisites

- Apply the shared SDLC conventions in `skills/sdlc/references/shared.md`.
- If no argument is provided, locate the feature directory under `.sdlc/features/` whose frontmatter `issue` field references `$ISSUE_NUMBER`.
- `.sdlc/features/N-<slug>/specification.md` (must have passed review with findings verdict `approved`), or a specification document provided in context or as a file path (`$1`)
- `.sdlc/features/N-<slug>/lifecycle.md` (optional, if a lifecycle document was produced): track state transitions as analytics events to measure flow through lifecycle stages
- `.sdlc/features/N-<slug>/requirements.md` (optional, for cross-referencing acceptance criteria)

## Steps

1. Read the specification, lifecycle document (if present), and requirements documents.
2. Identify the key user flows and system interactions from the specification.
3. For each flow, determine what events should be tracked to measure adoption, completion, and failure.
4. Define success metrics that answer: "How do we know this feature is successful?"
5. Define funnel steps for critical user journeys, rendered as a Mermaid `flowchart TD` with one node per step labeled by its event, so a gap or an unreachable step in the funnel is easy to see.
6. Specify the event taxonomy: event names, properties, and where they fire.
7. Identify any counter metrics (signs the feature might be causing harm).
8. Determine telemetry infrastructure requirements (existing vs. new instrumentation).
9. Write the output to `.sdlc/features/N-<slug>/telemetry.md`.

## Output Format

Use the template at `skills/sdlc/templates/features/telemetry.md` (copied to `.sdlc/templates/features/telemetry.md` by `/initialize-sdlc-directory`; use the project's customized copy if present). Write the result to the artifact path named in the steps above.

## Event Naming Conventions

Follow these conventions for consistency across features:

- Use `snake_case` for event names: `user_signup_completed`, `order_payment_failed`
- Use `<entity>_<action>_<status>` pattern where applicable: `invoice_export_started`, `invoice_export_completed`, `invoice_export_failed`
- Prefix with feature name for namespacing when the analytics platform requires it
- Properties should be primitive types (string, number, boolean) to ensure queryability
- Include a `source` property on every event to distinguish client vs. server emission

## Success Metrics Guidance

Good success metrics are:
- **Measurable:** Tied to a specific number or ratio, not subjective
- **Actionable:** If the metric moves in the wrong direction, there is a clear response
- **Time-bound:** Measured over a defined period (first week, first month, etc.)

Common metric types:
- **Adoption:** % of eligible users who use the feature at least once
- **Engagement:** Average uses per user per week
- **Completion rate:** % of users who finish a multi-step flow
- **Time-to-value:** Median time from feature discovery to first successful use
- **Error rate:** % of interactions that result in an error

## Outcome

If `$OUTCOME_YAML` is set, emit `verdict: approved` there per `skills/sdlc/references/shared.md`, If the artifact could not be produced, omit the file.
In the same emission, list the artifact under `artifacts:` (`.sdlc/features/N-<slug>/telemetry.md`).

## Example Usage

**Scenario 1: New notification system**
Requirements describe a notification center with email and in-app notifications.
Success metrics: 70% of users view notifications within 24h, < 2% unsubscribe rate.
Funnel: notification_sent → notification_viewed → notification_clicked → target_action_completed.
Counter metrics: notification_delivery_failure_rate > 1%.

**Scenario 2: API endpoint for file uploads**
Requirements describe a bulk file upload feature.
Success metrics: 95% upload success rate, median upload time < 5s for 10MB files.
Events: upload_started (with file_count, total_bytes), upload_completed, upload_failed (with error_type).
Counter metrics: retry_rate > 10%, user_abandonment_after_failure > 50%.

**Scenario 3: Internal tool dashboard**
Requirements describe an admin analytics dashboard.
Success metrics: 80% of admins use it weekly, average session time 2-5 minutes (not too short = confused, not too long = struggling).
Events: dashboard_viewed, filter_applied (with filter_type), export_clicked.

## Completion Checklist

Before handing off to review, confirm:

- [ ] Success metrics measurable and time-bound, and counter metrics (signs of harm) defined too
- [ ] Every event includes a `source` property and follows the `<entity>_<action>_<status>` naming pattern
- [ ] Every funnel rendered as a Mermaid `flowchart TD` whose node labels carry the marking event

Self-check the draft against the [`review-telemetry` checklist](../review-telemetry/SKILL.md) and fix what you can, so review finds less to flag.

## Next Step

A review subagent is dispatched automatically to run `/review-telemetry` to audit the telemetry plan for completeness, actionability, and consistency before moving on.
Once approved, continue with `/create-plan`.

## Useful Commands Reference

| Command | Description |
|---|---|
| `mmdc -i <diagram.mmd>` or `npx -y @mermaid-js/mermaid-cli` | Best-effort Mermaid render check for the funnel flowcharts |