# Product Tracking Workflow

<template_meta>
name: product-tracking
version: 1
requires_project: false
artifact_dir: .sf/workflows/product-tracking/
</template_meta>

<purpose>
Make a product data-ready by turning product behavior into a versioned telemetry
contract, implementation guide, and verified tracking code. The workflow protects
product, growth, customer success, and engineering consumers from analytics that
are missing, inconsistent, or impossible to trust.
</purpose>

<phases>
1. model - Document what the product does, who uses it, and which entities matter
2. audit - Capture the analytics and identity wiring that already exists
3. plan - Design the target tracking plan and explicit delta from current state
4. instrument - Generate SDK-specific implementation guidance
5. implement - Add or update tracking code against the guide
6. verify - Prove the tracking contract and implementation are usable
</phases>

<process>

## Phase 1: Model Product

**Goal:** Produce `.telemetry/product.md`, the product model used by every later phase.

1. Inspect README, docs, routes, core domain modules, API handlers, UI flows, and tests.
2. Identify users, organizations/accounts, key workflows, value moments, and domain entities.
3. Write `.telemetry/product.md` with enough detail for a telemetry plan reviewer to understand why each event exists.
4. If an installed skill named `product-tracking-skills:product-tracking-model-product` is available, use it. If it is unavailable, follow this phase directly.

**Completion evidence:**
- `.telemetry/product.md` exists.
- It names real product consumers and entities, not generic analytics concepts.
- Unknowns are marked as open questions instead of guessed.

## Phase 2: Audit Current Tracking

**Goal:** Produce `.telemetry/current-state.yaml` plus an audit note describing current SDK and instrumentation wiring.

1. Search for analytics SDK imports, network endpoints, server-side emitters, identity calls, group/account calls, feature flag exposure calls, and test helpers.
2. Record actual events, properties, user identity fields, group identity fields, destinations, and call sites.
3. Document failure or absence explicitly. "No current tracking found" is a valid audit result if supported by code search evidence.
4. If `product-tracking-skills:product-tracking-audit-current-tracking` is available, use it. If it is unavailable, follow this phase directly.

**Completion evidence:**
- `.telemetry/current-state.yaml` exists.
- The audit names the files or modules inspected.
- Missing or ambiguous wiring is represented as a gap, not silently ignored.

## Phase 3: Design Tracking Plan

**Goal:** Produce `.telemetry/tracking-plan.yaml` and `.telemetry/delta.md`.

1. Use `.telemetry/product.md` and `.telemetry/current-state.yaml` as the source of truth.
2. Define events, properties, entities, group hierarchy, identity rules, and lifecycle semantics.
3. Prefer fewer high-value events over noisy implementation events.
4. Write `.telemetry/delta.md` to separate what already exists from what must be added, renamed, removed, or fixed.
5. If `product-tracking-skills:product-tracking-design-tracking-plan` is available, use it. If it is unavailable, follow this phase directly.

**Completion evidence:**
- `.telemetry/tracking-plan.yaml` exists.
- `.telemetry/delta.md` exists.
- Every event has a production consumer or decision it supports.

## Phase 4: Generate Instrument Guide

**Goal:** Produce `.telemetry/instrument.md`, the SDK-specific implementation guide for the target destination.

1. Determine the destination from user input, existing SDKs, or the `tracking_destination` parameter. If unclear, document the assumed destination and confidence.
2. Explain identify, group/account, track, feature exposure, and page/screen tracking patterns that apply to this repo.
3. Include concrete examples in the repo's language and framework.
4. Include privacy, PII, environment, batching, and server/client boundary constraints.
5. If `product-tracking-skills:product-tracking-instrument-guide` is available, use it. If it is unavailable, follow this phase directly.

**Completion evidence:**
- `.telemetry/instrument.md` exists.
- It is specific enough that an implementer can add code without re-deciding SDK semantics.
- Unsupported capabilities of the destination are called out.

## Phase 5: Implement Tracking

**Goal:** Add or update typed tracking code using `.telemetry/instrument.md` and `.telemetry/tracking-plan.yaml`.

1. Create or update a small tracking module/wrapper that centralizes SDK calls.
2. Add typed event helpers or schemas where the repo language supports them.
3. Wire identity and group calls at real login/account/session boundaries.
4. Instrument the highest-value events from `.telemetry/delta.md`; do not sprinkle ad hoc calls outside the wrapper.
5. Add focused tests for wrapper behavior, identity mapping, and at least one real consumer path.
6. If `product-tracking-skills:product-tracking-implement-tracking` is available, use it. If it is unavailable, follow this phase directly.

**Completion evidence:**
- Tracking code exists in the repo, not only in docs.
- Tests or smoke checks prove at least one event path and identity path.
- `.telemetry/delta.md` is updated to show what remains.

## Phase 6: Verify Tracking

**Goal:** Prove the telemetry contract is coherent and the implementation can ship.

1. Run the repo's focused tests, typecheck, lint, or build command relevant to the tracking changes.
2. Review generated events against `.telemetry/tracking-plan.yaml` for naming, required properties, identity, and PII constraints.
3. Write a short verification note in the artifact directory or `.telemetry/verification.md`.
4. If verification cannot run, document the blocker and the exact command or environment needed.

**Completion evidence:**
- Verification commands and results are recorded.
- Any remaining telemetry gaps are listed as explicit follow-up work.
- The final state identifies what product questions can now be answered.

</process>
