Update to Accoil Product Tracking

{
  "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.'\n",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 248
    },
    {
      "relative_path": "references/anti-patterns.md",
      "size_in_bytes": 4995
    },
    {
      "relative_path": "references/event-categories.md",
      "size_in_bytes": 5145
    },
    {
      "relative_path": "references/naming-conventions.md",
      "size_in_bytes": 10164
    },
    {
      "relative_path": "references/persistence.md",
      "size_in_bytes": 5960
    }
  ],
  "name": "product-tracking-instrument-new-feature",
  "skill_md_contents": "---\nname: product-tracking-instrument-new-feature\ndescription: >\n  Update the tracking plan when a feature ships, changes, or is removed. Assesses\n  whether new events are needed, extends existing events with properties where possible,\n  and produces a versioned mini-delta with changelog entry. Updates\n  .telemetry/tracking-plan.yaml, delta.md, and changelog.md. Use when the user ships\n  a new feature, modifies existing functionality, wants to keep tracking coherent\n  as the product evolves, 'feature shipped,' 'new feature tracking,' 'update tracking\n  for [feature],' 'what tracking does this feature need,' or 'instrument new feature.'\nmetadata:\n  author: accoil\n  version: \"0.5\"\n---\n\n# Feature Instrumentation\n\nYou 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.\n\n## Reference Index\n\n| File | What it covers | When to read |\n|------|---------------|--------------|\n| `references/naming-conventions.md` | Event/property naming standards | Naming new events |\n| `references/persistence.md` | `.telemetry/` folder structure, changelog | Updating artifacts correctly |\n| `references/event-categories.md` | Event taxonomy and coverage | Categorizing new events |\n| `references/anti-patterns.md` | What to avoid in tracking | Reviewing new additions |\n\n## Goal\n\nWhen a feature ships or changes, determine:\n1. Does this need new tracking?\n2. Does it modify existing tracking?\n3. Does it need no tracking changes?\n\nThen produce a **mini delta** and update the target plan.\n\nOutput: updated `.telemetry/tracking-plan.yaml` + `.telemetry/delta.md` + `.telemetry/changelog.md`\n\n## Prerequisites\n\n**Check before starting:**\n\n1. **`.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.\"*\n2. **`.telemetry/product.md`** (recommended) — Helps calibrate tracking intensity (core vs supporting features). If missing, proceed but note the context gap.\n\n## Trigger Scenarios\n\n| Scenario | Response |\n|----------|----------|\n| New feature ships | Assess value, design events if needed, update plan |\n| Existing feature changes | Assess impact on existing events, modify or extend |\n| Feature removed | Deprecate related events, set removal timeline |\n| Audit findings to fix | Apply fixes from audit, update plan |\n| Periodic review | Check for stale events, coverage gaps |\n\n**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.\n\n## Process\n\n### 1. Understand the Change\n\nAsk:\n- \"What feature shipped or changed?\"\n- \"What are the key user actions in this feature?\"\n- \"Is this core value or supporting functionality?\"\n\nOr if working from a PR/commit/feature spec, read the context directly.\n\n### 2. Assess Tracking Need\n\nNot every feature needs new events. Ask:\n\n**Does this feature introduce new value?**\n- New user action that delivers value → probably needs an event\n- UI rearrangement of existing functionality → probably doesn't\n\n**Does it extend an existing flow?**\n- New step in existing workflow → maybe extend existing event with property\n- New variant of existing action → add enum value, not new event\n\n**Is it supporting or core?**\n- Core value feature → first-class event with rich properties\n- Supporting feature → appropriate but lighter coverage\n\n**The minimalist test:** \"Will anyone ever query this event in isolation?\" If not, it might be better as a property on an existing event.\n\n### 3. Design the Mini Delta\n\nFor new events:\n- Follow naming conventions (object.action, snake_case)\n- Assign category\n- Define properties with types\n- Set expected frequency\n- Assign group level\n\nFor B2C products without group hierarchy, skip group-level assignment — events are user-level only.\n\nFor modified events:\n- Assess breaking impact:\n\n| Change | Breaking? | Approach |\n|--------|-----------|----------|\n| Add optional property | No | Add directly |\n| Add required property | Yes | Make optional first, or version bump |\n| Expand enum | No | Add new values |\n| Restrict enum | Yes | Deprecation period |\n| Rename event | Yes | New event + deprecate old |\n| Change property type | Yes | New property, deprecate old |\n\nFor deprecated events:\n- Mark deprecated with reason and removal date\n- Document migration path if replacement exists\n- Keep in plan until removal date, then clean up\n\n### 4. Check Against Existing Events\n\nBefore adding new events:\n- Is there a similar event that could be extended with a property?\n- Would adding to an existing event make sense?\n- Are you creating a near-duplicate?\n\n**Properties over events:** `report.created` with `{ report_type: 'ai_generated' }` beats a separate `ai_report.created`.\n\n### 5. Update the Plan\n\nModify `.telemetry/tracking-plan.yaml`:\n\n**Adding events:**\n```yaml\n  - name: feature.action\n    category: core_value\n    description: User does the new thing\n    added_version: \"1.1.0\"\n    properties:\n      - name: property_name\n        type: string\n        required: true\n```\n\n**Deprecating events:**\n```yaml\n  - name: old_feature.action\n    deprecated: true\n    deprecated_version: \"1.1.0\"\n    deprecated_reason: \"Feature removed\"\n    remove_after: \"YYYY-MM-DD\"\n    migration: \"No replacement\" | \"Use new_feature.action\"\n```\n\nBump `meta.version` and `meta.updated`.\n\n### 6. Update the Changelog\n\nAppend to `.telemetry/changelog.md`:\n\n```markdown\n## [1.1.0] - YYYY-MM-DD\n\n### Added\n- `feature.action` event for [feature description]\n\n### Changed\n- `existing.event`: added optional `new_prop`\n\n### Deprecated\n- `old.event`: [reason] (removal: YYYY-MM-DD)\n\n### Migration Notes\n[If applicable]\n```\n\n### 7. Update the Delta\n\nIf `.telemetry/delta.md` exists, add the new changes. Otherwise create it.\n\n### 8. Document Implementation Locations\n\nFor each new or changed event, document in the delta:\n- **Where** in the codebase the tracking call should be added (file and function/handler)\n- **What** the event call should contain (event name, required properties, group context)\n- **Whether** identity or group calls need updating\n\nThis provides the implementation roadmap. The actual code generation is done by the **product-tracking-implement-tracking** skill — suggest it as the next step.\n\n## Versioning\n\nUse semantic versioning:\n- **Major (1.0 → 2.0):** Breaking changes (removed events, required properties added)\n- **Minor (1.0 → 1.1):** New events, new optional properties\n- **Patch (1.0.0 → 1.0.1):** Documentation, description fixes\n\n## Output Summary\n\nAfter every update, generate:\n\n```markdown\n# Tracking Plan Update\n\n**Version:** 1.0.0 → 1.1.0\n**Date:** YYYY-MM-DD\n**Reason:** [feature name]\n\n## Changes\n- Added: `feature.action`\n- Modified: `existing.event` (new optional property)\n- Deprecated: `old.event`\n\n## Implementation Required\n- [ ] Add tracking for `feature.action` in [location]\n- [ ] Update `existing.event` in [location]\n\n## Breaking Changes\nNone / [list]\n\n## Regenerate Code\nRun the **product-tracking-implement-tracking** skill to update SDK wrapper (e.g., *\"implement tracking\"*).\n```\n\n## Behavioral Rules\n\n1. **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.\n\n2. **Extend before adding.** Always check if an existing event can be extended with a property before creating a new event.\n\n3. **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.\n\n4. **Version everything.** Every change gets a version bump and changelog entry. No silent mutations.\n\n5. **Deprecate, don't delete.** Events get deprecated first, removed later. This gives consumers time to adjust.\n\n6. **Context matters.** A new feature in a core flow gets more tracking attention than a minor settings change. Use the product model to calibrate.\n\n7. **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.\n\n8. **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.\n\n9. **Present decisions, not deliberation.** Reason silently. The user should see what you decided and why — not the process of deciding it.\n\n## Lifecycle\n\n```\nmodel → audit → design → guide → implement ← feature updates\n                                                    ^\n```\n\n## Next Phase\n\nAfter feature instrumentation, suggest the user run:\n- **product-tracking-implement-tracking** — generate or update code for the new/changed events (e.g., *\"implement tracking\"*, *\"generate code\"*, *\"update tracking module\"*)\n- **product-tracking-audit-current-tracking** — optionally re-audit to verify the implementation matches (e.g., *\"audit tracking\"*, *\"verify tracking\"*)\n"
}