# Example: Product Tracking Lifecycle
# Demonstrates: a linear product telemetry workflow with durable handoff
# artifacts, context_from chaining, params, prompt verification, and an
# implementation verification step.

version: 1
name: product-tracking-lifecycle
description: >-
  Model a product, audit current analytics, design a product telemetry tracking
  plan, generate SDK-specific instrumentation guidance, implement tracking, and
  verify the resulting data contract.
params:
  tracking_destination: "existing analytics destination if one is present; otherwise generic HTTP"
  verification_command: "npm test"
steps:
  - id: model-product
    name: Model product telemetry surface
    prompt: >-
      Model the product so later telemetry decisions have a concrete source of
      truth. Inspect README, docs, routes, domain modules, API handlers, UI
      workflows, and tests. Write .telemetry/product.md in this workflow run
      with users, accounts or groups, value moments, core entities, key
      workflows, and open questions. Also mirror the file to the project root
      .telemetry/product.md when this repository is the real implementation
      target. Use product-tracking-skills:product-tracking-model-product if it
      is installed; otherwise complete the phase directly.
    requires: []
    produces:
      - .telemetry/product.md
    verify:
      policy: content-heuristic

  - id: audit-current-tracking
    name: Audit current tracking
    prompt: >-
      Audit the current analytics implementation. Search for analytics SDK
      imports, tracking emitters, identify calls, group or account calls, event
      constants, feature exposure calls, network endpoints, and tests. Write
      .telemetry/current-state.yaml in this workflow run with actual events,
      properties, identity fields, group fields, destinations, and call sites.
      Include a short audit note in .telemetry/current-state.md. Mirror durable
      artifacts to the project root .telemetry directory when this repository is
      the real implementation target. Use
      product-tracking-skills:product-tracking-audit-current-tracking if it is
      installed; otherwise complete the phase directly.
    requires:
      - model-product
    context_from:
      - model-product
    produces:
      - .telemetry/current-state.yaml
      - .telemetry/current-state.md
    verify:
      policy: content-heuristic

  - id: design-tracking-plan
    name: Design target tracking plan
    prompt: >-
      Design the target tracking plan from the product model and current-state
      audit. Write .telemetry/tracking-plan.yaml with events, properties,
      entities, identity rules, group hierarchy, and destination notes. Write
      .telemetry/delta.md separating existing tracking from additions, fixes,
      removals, and open questions. Every event must name the product question,
      operational decision, or downstream consumer it supports. Mirror durable
      artifacts to the project root .telemetry directory when this repository is
      the real implementation target. Use
      product-tracking-skills:product-tracking-design-tracking-plan if it is
      installed; otherwise complete the phase directly.
    requires:
      - audit-current-tracking
    context_from:
      - model-product
      - audit-current-tracking
    produces:
      - .telemetry/tracking-plan.yaml
      - .telemetry/delta.md
    verify:
      policy: content-heuristic

  - id: generate-instrument-guide
    name: Generate instrumentation guide
    prompt: >-
      Generate an SDK-specific implementation guide for {{ tracking_destination }}.
      Use the tracking plan and delta as inputs. Write .telemetry/instrument.md
      with concrete identify, group or account, track, page or screen, and
      feature exposure patterns that fit this repo. Include privacy, PII,
      environment, server/client boundary, batching, and unsupported-capability
      constraints. Mirror the guide to the project root .telemetry directory
      when this repository is the real implementation target. Use
      product-tracking-skills:product-tracking-instrument-guide if it is
      installed; otherwise complete the phase directly.
    requires:
      - design-tracking-plan
    context_from:
      - design-tracking-plan
    produces:
      - .telemetry/instrument.md
    verify:
      policy: content-heuristic

  - id: implement-tracking
    name: Implement tracking
    prompt: >-
      Implement the highest-value tracking changes from .telemetry/delta.md
      using .telemetry/instrument.md. Prefer a small centralized tracking module
      or wrapper, typed event helpers or schemas where the repo language
      supports them, and real identity or group wiring at login, account, or
      session boundaries. Add focused tests for wrapper behavior, identity
      mapping, and at least one real consumer path. Update .telemetry/delta.md
      with what was implemented and what remains. Use
      product-tracking-skills:product-tracking-implement-tracking if it is
      installed; otherwise complete the phase directly.
    requires:
      - generate-instrument-guide
    context_from:
      - design-tracking-plan
      - generate-instrument-guide
    produces:
      - .telemetry/implementation.md
      - .telemetry/delta.md
    verify:
      policy: content-heuristic
      minSize: 200

  - id: verify-tracking
    name: Verify tracking contract
    prompt: >-
      Verify the tracking implementation and contract. Run {{ verification_command }}
      if it is appropriate for this repository; otherwise run the nearest focused
      test, typecheck, lint, or build command and document why. Compare implemented
      events against .telemetry/tracking-plan.yaml for names, required
      properties, identity, group hierarchy, and PII constraints. Write
      .telemetry/verification.md with commands, results, blockers, and remaining
      follow-up work.
    requires:
      - implement-tracking
    context_from:
      - design-tracking-plan
      - implement-tracking
    produces:
      - .telemetry/verification.md
    verify:
      policy: content-heuristic
      minSize: 200
