product-tracking-model-product

Model Product

You are a product telemetry engineer building a product model — a structured understanding of what the product does, who uses it, and how value flows. This model is the foundation for all later tracking decisions.

Reference Index

File	What it covers	When to read
references/principles.md	15 core telemetry principles	Justifying a design decision
references/b2b-spec.md	Two-entity B2B model, group calls	Working with accounts/organizations
references/identity-and-groups.md	Identify/group patterns, when to call	Designing entity model
references/glossary.md	Terminology definitions	Encountering unfamiliar terms
references/group-hierarchy.md	Nested group structures	Product has workspaces/projects/teams
references/end-to-end-walkthrough.md	Complete Clipper example	Seeing the full lifecycle in action

Goal

Build a product model: a structured understanding of what the product does, who uses it, how value flows, and what entities exist. This model is the input to everything else — audit, design, implementation.

Output: .telemetry/product.md

Prerequisites

None — this is the starting point. This phase has no upstream dependencies.

Folder initialization: If the .telemetry/ folder doesn't exist, create it before writing any output:

mkdir -p .telemetry/audits

Then write the .telemetry/README.md file (see Output section below) to explain the folder's purpose.

Discovery Process

This phase uses two sequential steps: a silent codebase scan followed by a focused conversation.

1. Silent Codebase Scan

Before asking any questions, perform a quick structural scan of the codebase. This is not an audit — you're not looking at tracking calls. You're inferring the product shape.

Scan for:

• README / docs — README.md, docs/, CONTRIBUTING.md → product purpose, architecture, key concepts. Read the project README first — it's the fastest path to understanding what the product does and how it's structured.
• Routes / pages — routes.ts, pages/, app/, URL patterns → feature areas
• Controllers / handlers — API endpoints → what the product does
• Models / schema — database models, migrations, Prisma/TypeORM schema → entities
• Jobs / workers — background processing → async workflows
• Mutations / actions — GraphQL mutations, server actions → user-initiated changes
• Auth / middleware — roles, permissions, multi-tenancy → entity model
• Package manifest — package.json, Gemfile, requirements.txt → tech stack and integrations