Copilot instructions

1---
2applyTo: 'apps/studio/**,packages/common/telemetry*'
3---
4 
5# Studio Telemetry Review Rules
6 
7All comments are **advisory** — suggest, do not request changes.
8 
9## When to Flag Missing Telemetry
10 
11Use judgment — not every PR needs telemetry. But **always flag** when:
12 
131. **Changes to `packages/common/telemetry-constants.ts`** — validate event naming, property conventions, and JSDoc accuracy.
142. **PostHog feature flags without measurement.** If a PR uses `usePHFlag` or PostHog-backed hooks like `useDataApiRevokeOnCreateDefaultEnabled` to gate behavior, the flag state should be captured in a telemetry event so the rollout can be measured. Flag if the flag value isn't included in a relevant `track()` call. (Note: `useFlag` from `common` reads ConfigCat flags, not PostHog — different system, different guidance.)
153. **Feature-flagged rollouts without outcome tracking.** If a flag gates new behavior, there should be telemetry on both the flag state _and_ how users respond to the new behavior (e.g., toggle clicks, opt-in actions).
164. **Growth-oriented components adding user interactions without tracking** — onboarding flows, setup wizards, upgrade CTAs, A/B experiment variants.
17 
18When tracking is missing, comment: _"This adds a user interaction (or feature flag) that may benefit from tracking."_ Then propose an event name and `useTrack()` call.
19 
20## Feature Flag Telemetry Pattern
21 
22When capturing a PostHog flag value for telemetry, read the raw flag via `usePHFlag('flagName')` — **not** through wrapper hooks that coerce `undefined` to `false`. Use conditional spread so the property is omitted (not false) when the flag store hasn't loaded:
23 
24```typescript
25const flagValue = usePHFlag<boolean>('myBooleanFlag') // for boolean flags
26track('event_name', {
27  ...(flagValue !== undefined && { myFlagEnabled: flagValue }),
28})
29```
30 
31For string-valued flags (e.g., experiment variants), use `usePHFlag<string>('flagName')` instead.
32 
33## Event Naming
34 
35Format: `[object]_[verb]` in snake_case.
36 
37Prefer verbs already in use in `packages/common/telemetry-constants.ts`: `opened`, `clicked`, `submitted`, `created`, `removed`, `updated`, `intended`, `evaluated`, `added`, `enabled`, `disabled`, `copied`, `exposed`, `failed`, `converted`, `closed`, `completed`, `applied`, `sent`, `moved`.
38 
39Flag: unapproved verbs (`saved`, `viewed`, `pressed`), wrong order (`click_product_card`), wrong casing (`productCardClicked`), passive view tracking on page load (exception: `_exposed` events for A/B experiments).
40 
41## Event Properties
42 
43- **camelCase** for new events; match existing convention when extending
44- Self-explanatory names — flag generic (`label`, `value`, `name`, `data`)
45- Check `telemetry-constants.ts` for consistency with similar events
46- Never track PII
47 
48## Event Implementation
49 
50- Use `useTrack` from `lib/telemetry/track` — avoid introducing new `useSendEventMutation` usage
51- New events need a TypeScript interface in `telemetry-constants.ts` with `@group Events` and `@source` JSDoc tags (add `@page` when applicable for page-specific events), added to the `TelemetryEvent` union
52 
53```typescript
54import { useTrack } from 'lib/telemetry/track'
55 
56const track = useTrack()
57track('product_card_clicked', { productType: 'database', planTier: 'pro' })
58```
59 
60Canonical standards: `.claude/skills/telemetry-standards/SKILL.md`
61