Update to Accoil Product Tracking

{
  "description": "Build a structured product model by scanning the codebase and talking to the user. Produces .telemetry/product.md — a description of what the product does, who uses it, how value flows, and what entities exist. Use when starting telemetry work on a new codebase, when the user asks to 'model this product,' 'understand this product,' 'what does this product do,' 'map the product,' 'product model,' or when no .telemetry/product.md exists yet. This is the entry point for the telemetry lifecycle.\n",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 255
    },
    {
      "relative_path": "assets/telemetry-readme.md",
      "size_in_bytes": 1961
    },
    {
      "relative_path": "references/b2b-spec.md",
      "size_in_bytes": 8884
    },
    {
      "relative_path": "references/end-to-end-walkthrough.md",
      "size_in_bytes": 27227
    },
    {
      "relative_path": "references/glossary.md",
      "size_in_bytes": 4355
    },
    {
      "relative_path": "references/group-hierarchy.md",
      "size_in_bytes": 17172
    },
    {
      "relative_path": "references/identity-and-groups.md",
      "size_in_bytes": 11110
    },
    {
      "relative_path": "references/principles.md",
      "size_in_bytes": 5082
    }
  ],
  "name": "product-tracking-model-product",
  "skill_md_contents": "---\nname: product-tracking-model-product\ndescription: >\n  Build a structured product model by scanning the codebase and talking to the user.\n  Produces .telemetry/product.md — a description of what the product does, who uses it,\n  how value flows, and what entities exist. Use when starting telemetry work on a new\n  codebase, when the user asks to 'model this product,' 'understand this product,'\n  'what does this product do,' 'map the product,' 'product model,' or when no\n  .telemetry/product.md exists yet. This is the entry point for the telemetry lifecycle.\nmetadata:\n  author: accoil\n  version: \"0.5\"\n---\n\n# Model Product\n\nYou 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.\n\n## Reference Index\n\n| File                                   | What it covers | When to read |\n|----------------------------------------|---------------|--------------|\n| `references/principles.md`             | 15 core telemetry principles | Justifying a design decision |\n| `references/b2b-spec.md`               | Two-entity B2B model, group calls | Working with accounts/organizations |\n| `references/identity-and-groups.md`    | Identify/group patterns, when to call | Designing entity model |\n| `references/glossary.md`               | Terminology definitions | Encountering unfamiliar terms |\n| `references/group-hierarchy.md`        | Nested group structures | Product has workspaces/projects/teams |\n| `references/end-to-end-walkthrough.md` | Complete Clipper example | Seeing the full lifecycle in action |\n\n## Goal\n\nBuild 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.\n\nOutput: `.telemetry/product.md`\n\n## Prerequisites\n\n**None — this is the starting point.** This phase has no upstream dependencies.\n\n**Folder initialization:** If the `.telemetry/` folder doesn't exist, create it before writing any output:\n\n```bash\nmkdir -p .telemetry/audits\n```\n\nThen write the `.telemetry/README.md` file (see Output section below) to explain the folder's purpose.\n\n## Discovery Process\n\nThis phase uses **two sequential steps**: a silent codebase scan followed by a focused conversation.\n\n### 1. Silent Codebase Scan\n\nBefore 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.\n\n**Scan for:**\n- **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.\n- **Routes / pages** — `routes.ts`, `pages/`, `app/`, URL patterns → feature areas\n- **Controllers / handlers** — API endpoints → what the product does\n- **Models / schema** — database models, migrations, Prisma/TypeORM schema → entities\n- **Jobs / workers** — background processing → async workflows\n- **Mutations / actions** — GraphQL mutations, server actions → user-initiated changes\n- **Auth / middleware** — roles, permissions, multi-tenancy → entity model\n- **Package manifest** — `package.json`, `Gemfile`, `requirements.txt` → tech stack and integrations\n\n**Build an inferred view:**\n- What entities exist? (users, accounts, projects, etc.)\n- What are the main feature areas? (from routes/controllers)\n- What workflows are there? (from jobs, mutations)\n- What does the product likely do?\n\n**Do NOT:**\n- Read every file — scan patterns and names\n- Look at tracking/analytics code — that's audit\n- Spend more than 2-3 minutes on this pass\n- Present raw findings to the user — synthesize first\n\n### 2. Conversation with User\n\nUse the inferred view to have a more informed conversation. You're not starting from zero — you have hypotheses to validate.\n\n**Key areas to cover:**\n- **Product identity:** category, primary value action, what failure looks like. Lead with what you inferred: \"This looks like a [category] product that [does X]. Is that right?\"\n- **Value mapping:** core features (directly deliver value) vs supporting features (enable core). \"What's the action that, if it dropped to zero, would mean the product has failed?\"\n- **Entity model:** how users/accounts/groups relate, roles, multi-tenancy. \"I found models for [entities]. How do they relate?\"\n- **Group hierarchy depth:** \"How many levels should we track? Most products benefit from 2-3 levels (e.g., Account → Workspace). Going deeper adds group() call complexity for diminishing analytical returns. Where should we draw the line?\" Not all products have group hierarchy — B2C products may only need user-level tracking.\n- **Business model:** monetization approach, pricing tiers (check for Stripe/billing code in Gemfile/package.json), free vs paid features. This matters for telemetry — conversion and upgrade events depend on knowing the tiers.\n- **Current state:** existing tracking tools, biggest gaps, pain points\n- **Integration targets:** where telemetry data needs to go (analytics tools, CDPs, data warehouses)\n\n**Destination suggestions:** When asking about analytics destinations, start from what the codebase already uses. If nothing is in place, offer a few common options (e.g., Segment, Amplitude, Mixpanel, PostHog, Accoil) without favoring any one.\n\n**Flag destination constraints early.** If a destination has design-altering constraints, note them in product.md's Integration Targets section. For example, if the user selects Accoil, note: \"Accoil — event names only, no properties stored. Don't encode variants in event names; descriptive context goes on user/account traits.\" Don't require deep knowledge of every destination — just note what you know from the references.\n\n## Behavioral Rules\n\n1. **Scan first, ask second.** Always do the silent codebase pass before starting the conversation. Use what you learn to ask better questions.\n\n2. **Synthesize, don't dump.** Never present raw file lists to the user. Translate what you found into product concepts: \"This looks like a project management tool with workspaces, tasks, and team collaboration.\" Never paste more than 20 lines of raw data into the conversation — write detailed findings to files and show summaries.\n\n3. **Validate, don't assume.** The codebase gives you hypotheses. The conversation confirms or corrects them.\n\n4. **Product focus, not code focus.** You're building a product model, not a code review or database diagram. Routes and models tell you what the product does — that's what matters. The Entity Model section should describe entities as a product person would understand them (users, accounts, boards), not as a database schema with join tables, foreign keys, and polymorphic associations. If your entity model reads like an ER diagram, you've gone too deep.\n\n5. **Ask about value, not features.** \"What matters?\" is more important than \"What exists?\" Every product has features; product modeling is about which ones matter and why.\n\n6. **Capture hierarchy early.** Most B2B products have structure beyond users and accounts. Probe for it — the tracking plan needs to know where events happen.\n\n7. **Stay lightweight.** This is product modeling, not a deep audit. If you find yourself reading implementation details, you've gone too far.\n\n8. **Traits belong in design, not here.** Product modeling identifies who the entities are and how they relate — not what traits to track on them. Trait design happens in the design phase, informed by the audit (what exists) and the product model (what matters).\n\n9. **No unknowns or placeholders.** Never write \"unknown\" or \"to be determined.\" State what you know, or explain why something isn't determinable from the codebase alone (e.g., \"Not visible from code; requires user input\").\n\n10. **Fill every template field.** Verify all sections of product.md are populated, including ID formats. If an ID format is just a database integer, say so.\n\n11. **Present decisions, not deliberation.** Reason silently. The user should see what you concluded and why — not the process of concluding it.\n\n12. **Make the one-liner vivid.** The one-liner in Product Identity should instantly tell a non-technical person what the product does — not a marketing tagline, but a concrete description of the core user action. \"Teams create boards of cards to track issues and move them through a workflow until resolved\" is better than \"A Kanban-style issue tracking application.\"\n\n## Output Format\n\nSave to `.telemetry/product.md`:\n\n```markdown\n# Product: [Name]\n\n**Last updated:** [date]\n**Method:** codebase scan + conversation\n\n## Product Identity\n- **One-liner:** [A vivid, plain-English sentence describing what the product does for its users — not a tagline, but something a non-technical person would immediately understand. E.g., \"Teams create boards of cards to track issues and move them through a workflow until resolved.\"]\n- **Category:** [b2b-saas, ai-ml-tool, etc.]\n- **Product type:** B2B / B2C / hybrid — If B2B, group hierarchy and account-level tracking apply. If B2C or hybrid, entity model may only need users.\n- **Collaboration:** single-player / multiplayer / hybrid\n\n## Business Model\n- **Monetization:** [free / freemium / paid-only / open-source with hosted offering]\n- **Pricing tiers:** [list tiers if visible from code, e.g., Free (1000 items), Pro ($20/mo), Enterprise]\n- **Billing integration:** [Stripe, Paddle, none detected, etc.]\n\n## Tech Stack\n- **Primary language:** [Ruby, Python, TypeScript, Go, etc.]\n- **Framework:** [Rails, Django, Next.js, Express, etc.]\n- **Database:** [PostgreSQL, MySQL, SQLite, MongoDB, etc.]\n- **Background jobs:** [Sidekiq, Celery, Bull, etc. — or none detected]\n- **HTTP client patterns:** [Faraday, requests, fetch, Net::HTTP, etc.]\n- **Module organization:** [Rails concerns, Python packages, TS modules, etc.]\n\n## Value Mapping\n\n### Primary Value Action\n**[Action]** — [description]. If this drops to zero, the product has failed.\n\n### Core Features (directly deliver value)\n1. **[Feature]** — [why it's core]\n2. **[Feature]** — [why it's core]\n\n### Supporting Features (enable core actions)\n1. **[Feature]** — [what it supports]\n2. **[Feature]** — [what it supports]\n\n## Entity Model\n\n### Users\n- **ID format:** [format, e.g. integer, UUID, prefixed string]\n- **Roles:** [list]\n- **Multi-account:** yes/no\n\n### Accounts\n- **ID format:** [format]\n- **Hierarchy:** flat / nested\n\n## Group Hierarchy\n\n```\n[Top Level]\n└── [Level 2]\n    └── [Level 3]\n```\n\n| Group Type | Parent | Where Actions Happen |\n|------------|--------|---------------------|\n| ... | ... | ... |\n\n**Default event level:** [most specific level]\n**Admin actions at:** [higher level]\n\n## Current State\n- **Existing tracking:** [tool or none]\n- **Documentation:** yes/no/partial\n- **Known issues:** [list]\n\n## Integration Targets\n| Destination | Purpose | Priority |\n|-------------|---------|----------|\n| ... | ... | ... |\n\n## Codebase Observations\n- **Feature areas inferred:** [from routes/controllers]\n- **Entity model inferred:** [from models/schema]\n```\n\n### `.telemetry/README.md` (first run only)\n\nIf the `.telemetry/` folder is new, copy [assets/telemetry-readme.md](assets/telemetry-readme.md) to `.telemetry/README.md`. If `.telemetry/README.md` already exists, leave it as-is.\n\n## What product.md Is NOT\n\n- Not an audit (no tracking coverage stats)\n- Not a tracking plan (no event definitions or trait designs)\n- Not working notes (no progress tracking)\n- Not implementation details (no code references)\n\nIt is a **static product description** that informs all later phases. Trait design (what to track on users, accounts, and groups) happens in the design phase.\n\n## Lifecycle\n\n```\nmodel → audit → design → guide → implement ← feature updates\n^\n```\n\n## Next Phase\n\nAfter product modeling, suggest the user run:\n- **product-tracking-audit-current-tracking** — capture current tracking reality (e.g., *\"audit tracking\"*, *\"what's currently tracked?\"*, *\"scan for analytics\"*)\n- **product-tracking-design-tracking-plan** — design the target tracking plan (e.g., *\"design tracking plan\"*, *\"what should we track?\"*)\n"
}