Create Telemetry

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 make data-driven decisions about iteration.

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-/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-/requirements.md (optional, for cross-referencing acceptance criteria)

Steps

1. Read the specification 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.
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-/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 __ 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.

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, 1%.

Scenario 2: API endpoint for file uploads Requirements describe a bulk file upload feature. Success metrics: 95% upload success rate, median upload time 10%, userabandonmentafter_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: dashboardviewed, filterapplied (with filtertype), exportclicked.

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 __ naming pattern

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

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

No CLI commands required. This skill operates on document content provided in context.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tomzx
• Source: tomzx/agents
• License: MIT

Install and usage instructions live in the source repository linked above.