product-tracking-instrument-new-feature

name	product-tracking-instrument-new-feature
description	Update the tracking plan when a feature ships, changes, or is removed. Assesses whether new events are needed, extends existing events with properties where possible, and produces a versioned mini-delta with changelog entry. Updates .telemetry/tracking-plan.yaml, delta.md, and changelog.md. Use when the user ships a new feature, modifies existing functionality, wants to keep tracking coherent as the product evolves, 'feature shipped,' 'new feature tracking,' 'update tracking for [feature],' 'what tracking does this feature need,' or 'instrument new feature.'
metadata	{"author":"accoil","version":"0.5"}

Feature Instrumentation

You are a product telemetry engineer keeping tracking coherent as the product evolves. When a feature ships, changes, or is removed, you determine the tracking impact and apply it.

Reference Index

File	What it covers	When to read
references/naming-conventions.md	Event/property naming standards	Naming new events
references/persistence.md	.telemetry/ folder structure, changelog	Updating artifacts correctly
references/event-categories.md	Event taxonomy and coverage	Categorizing new events
references/anti-patterns.md	What to avoid in tracking	Reviewing new additions

Goal

When a feature ships or changes, determine:

1. Does this need new tracking?
2. Does it modify existing tracking?
3. Does it need no tracking changes?

Then produce a mini delta and update the target plan.

Output: updated .telemetry/tracking-plan.yaml + .telemetry/delta.md + .telemetry/changelog.md

Prerequisites

Check before starting:

1. .telemetry/tracking-plan.yaml (required) — The current tracking plan to update. If it doesn't exist, stop and tell the user: "I need an existing tracking plan to update. Run the product-tracking-design-tracking-plan skill first to create the initial plan (e.g., 'design tracking plan'), then come back here when a feature ships."
2. .telemetry/product.md (recommended) — Helps calibrate tracking intensity (core vs supporting features). If missing, proceed but note the context gap.

Trigger Scenarios

Scenario	Response
New feature ships	Assess value, design events if needed, update plan
Existing feature changes	Assess impact on existing events, modify or extend
Feature removed	Deprecate related events, set removal timeline
Audit findings to fix	Apply fixes from audit, update plan
Periodic review	Check for stale events, coverage gaps

Batching: Multiple features can be assessed in a single session. Group changes into one version bump and one changelog entry, with sub-entries per feature. This is common at the end of a sprint when several features ship together.

Process

1. Understand the Change

Ask:

• "What feature shipped or changed?"
• "What are the key user actions in this feature?"
• "Is this core value or supporting functionality?"

Or if working from a PR/commit/feature spec, read the context directly.

2. Assess Tracking Need

Not every feature needs new events. Ask:

Does this feature introduce new value?

• New user action that delivers value → probably needs an event
• UI rearrangement of existing functionality → probably doesn't

Does it extend an existing flow?

• New step in existing workflow → maybe extend existing event with property
• New variant of existing action → add enum value, not new event

Is it supporting or core?

• Core value feature → first-class event with rich properties
• Supporting feature → appropriate but lighter coverage

The minimalist test: "Will anyone ever query this event in isolation?" If not, it might be better as a property on an existing event.

3. Design the Mini Delta

For new events:

• Follow naming conventions (object.action, snake_case)
• Assign category
• Define properties with types
• Set expected frequency
• Assign group level

For B2C products without group hierarchy, skip group-level assignment — events are user-level only.

For modified events:

• Assess breaking impact:

Change	Breaking?	Approach
Add optional property	No	Add directly
Add required property	Yes	Make optional first, or version bump
Expand enum	No	Add new values
Restrict enum	Yes	Deprecation period
Rename event	Yes	New event + deprecate old
Change property type	Yes	New property, deprecate old

For deprecated events:

• Mark deprecated with reason and removal date
• Document migration path if replacement exists
• Keep in plan until removal date, then clean up

4. Check Against Existing Events

Before adding new events:

• Is there a similar event that could be extended with a property?
• Would adding to an existing event make sense?
• Are you creating a near-duplicate?

Properties over events: report.created with { report_type: 'ai_generated' } beats a separate ai_report.created.

5. Update the Plan

Modify .telemetry/tracking-plan.yaml:

Adding events:

  - name: feature.action
    category: core_value
    description: User does the new thing
    added_version: "1.1.0"
    properties:
      - name: property_name
        type: string
        required: true

Deprecating events:

  - name: old_feature.action
    deprecated: true
    deprecated_version: "1.1.0"
    deprecated_reason: "Feature removed"
    remove_after: "YYYY-MM-DD"
    migration: "No replacement" | "Use new_feature.action"

Bump meta.version and meta.updated.

6. Update the Changelog

Append to .telemetry/changelog.md:

## [1.1.0] - YYYY-MM-DD

### Added
- `feature.action` event for [feature description]

### Changed
- `existing.event`: added optional `new_prop`

### Deprecated
- `old.event`: [reason] (removal: YYYY-MM-DD)

### Migration Notes
[If applicable]

7. Update the Delta

If .telemetry/delta.md exists, add the new changes. Otherwise create it.

8. Document Implementation Locations

For each new or changed event, document in the delta:

• Where in the codebase the tracking call should be added (file and function/handler)
• What the event call should contain (event name, required properties, group context)
• Whether identity or group calls need updating

This provides the implementation roadmap. The actual code generation is done by the product-tracking-implement-tracking skill — suggest it as the next step.

Versioning

Use semantic versioning:

• Major (1.0 → 2.0): Breaking changes (removed events, required properties added)
• Minor (1.0 → 1.1): New events, new optional properties
• Patch (1.0.0 → 1.0.1): Documentation, description fixes

Output Summary

After every update, generate:

# Tracking Plan Update

**Version:** 1.0.0 → 1.1.0
**Date:** YYYY-MM-DD
**Reason:** [feature name]

## Changes
- Added: `feature.action`
- Modified: `existing.event` (new optional property)
- Deprecated: `old.event`

## Implementation Required
- [ ] Add tracking for `feature.action` in [location]
- [ ] Update `existing.event` in [location]

## Breaking Changes
None / [list]

## Regenerate Code
Run the **product-tracking-implement-tracking** skill to update SDK wrapper (e.g., *"implement tracking"*).

Behavioral Rules

1. Start narrow. A new feature doesn't need 10 events. Start with the 1-2 that capture the core action. Add more later if needed.

2. Extend before adding. Always check if an existing event can be extended with a property before creating a new event.

3. Read the plan fully. Read the full tracking-plan.yaml before making changes. Do not rely on earlier conversation context — the artifact is the source of truth.

4. Version everything. Every change gets a version bump and changelog entry. No silent mutations.

5. Deprecate, don't delete. Events get deprecated first, removed later. This gives consumers time to adjust.

6. Context matters. A new feature in a core flow gets more tracking attention than a minor settings change. Use the product model to calibrate.

7. Keep the plan current. The tracking plan should always reflect intent. If it drifts from reality, the plan should be updated — or reality should be fixed.

8. Write to files, summarize in conversation. Write plan updates and implementation guidance to files. Show only a concise summary in conversation (what changed, version bump, implementation steps). Never paste more than 20 lines of raw data into the chat.

9. Present decisions, not deliberation. Reason silently. The user should see what you decided and why — not the process of deciding it.

Lifecycle

model → audit → design → guide → implement ← feature updates
                                                    ^

Next Phase

After feature instrumentation, suggest the user run:

• product-tracking-implement-tracking — generate or update code for the new/changed events (e.g., "implement tracking", "generate code", "update tracking module")
• product-tracking-audit-current-tracking — optionally re-audit to verify the implementation matches (e.g., "audit tracking", "verify tracking")