[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7B30P04XVXCBTJC2KT0Y4JM":3,"skill-same:01M7B30P04XVXCBTJC2KT0Y4JM":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7B30P04XVXCBTJC2KT0Y4JM","hamster-posthog-dashboards",null,"Use this skill whenever the user asks to review, analyse, investigate, duplicate, or build a PostHog dashboard for Hamster Studio. Drives the workflow that turns a dashboard ID (or a request to build one) into a snapshot, an analysis report, and prioritised follow-ups. Captures the doc structure (`posthog-reports\u002F`, `posthog-snapshots\u002F`, `posthog-insights-scope.md`, `posthog-insights-progress.md`, `posthog-events-inventory.md`) and the scripts in `packages\u002Fglass-box\u002Fscripts\u002F`.","gethamster\u002Fskills","gethamster","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F215697643?v=4","01M7B2R6PGB3SDZZ71E0WE2S74","Hamster","01M7B2R6Q21HWJRXZZWB78BNDG",4,"MIT","https:\u002F\u002Fgithub.com\u002Fgethamster\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002F.experimental\u002Fhamster-posthog-dashboards\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: hamster-posthog-dashboards\ndescription: \"Use this skill whenever the user asks to review, analyse, investigate, duplicate, or build a PostHog dashboard for Hamster Studio. Drives the workflow that turns a dashboard ID (or a request to build one) into a snapshot, an analysis report, and prioritised follow-ups. Captures the doc structure (`posthog-reports\u002F`, `posthog-snapshots\u002F`, `posthog-insights-scope.md`, `posthog-insights-progress.md`, `posthog-events-inventory.md`) and the scripts in `packages\u002Fglass-box\u002Fscripts\u002F`.\"\nversion: \"1.0.0\"\n---\n\n# hamster-posthog-dashboards\n\nThis skill is the contract between Claude and the PostHog dashboard analysis system in Hamster Studio. When the user references a dashboard ID, asks to \"review,\" \"investigate,\" \"build,\" \"duplicate,\" or \"compare\" a dashboard, or asks to spawn a follow-up analysis, follow the patterns below.\n\n## When to invoke\n\n- \"Review dashboard `\u003Cid>`\" \u002F \"look at dashboard `\u003Cid>`\" \u002F \"what's in `\u003Cid>`?\"\n- \"Pull data from `\u003Cid>`\" \u002F \"compare against the spec\" \u002F \"is this dashboard right?\"\n- \"Investigate `\u003Cfinding>` from the LLM cost dashboard\"\n- \"Duplicate dashboard `\u003Cid>` to dev\" \u002F \"promote this dashboard to prod\"\n- \"Build a new dashboard for `\u003Ctopic>`\"\n- \"What's our LLM cost looking like?\" (implies pulling current data + writing\u002Fupdating a report)\n\n## When NOT to invoke\n\n- The user is talking about Mixpanel or Segment dashboards — this skill is PostHog-specific.\n- The user is asking about analytics *event instrumentation* in code (use `hamster-analytics` instead).\n- The user wants raw event-level data for one user to debug a bug — use the glass-box `PostHogClient` directly via `packages\u002Fglass-box\u002Freplay\u002Futils\u002Fposthog_client.py` rather than going through this skill's report workflow.\n\n## The doc structure (read before doing anything)\n\nFive surfaces, each with one job:\n\n| Surface | Purpose | Path |\n| --- | --- | --- |\n| Spec | What dashboards we want, with PostHog AI prompts | `docs\u002Farchitecture\u002Fposthog-insights-scope.md` |\n| Inventory | Typed catalog + drift | `docs\u002Farchitecture\u002Fposthog-events-inventory.md` |\n| Status board | One row per dashboard with link to latest report | `docs\u002Farchitecture\u002Fposthog-insights-progress.md` |\n| Snapshots | Raw data — definitions + cached results from PostHog | `docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.{md,json}` |\n| Reports | **Distilled analysis chains, per topic** | `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002F\u003Ctopic>\u002F\u003CNNN>-\u003Cslug>.md` |\n\n**Never put numbers or per-tile reviews in the spec or status board.** They go in reports.\n**Never edit a snapshot file by hand.** They are written by the inspector script.\n**Never edit a report after it has been issued (status `action-items-issued` or later).** Write a new numbered report instead. Reports are append-only.\n\nThe full structure plus templates is documented in `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002FREADME.md` and the topic READMEs.\n\n## The scripts\n\nBoth live in `packages\u002Fglass-box\u002Fscripts\u002F` and use `.env.\u003Cenv>` files populated by `pnpm get-env-qa`. Each needs `POSTHOG_DASHBOARD_API_KEY` (personal API key with `dashboard:read`, `insight:read` minimum; `dashboard:write` and `insight:write` for duplication) and `POSTHOG_PROJECT_ID` (or `POSTHOG_PROD_PROJECT_ID`).\n\n### inspect_posthog_dashboard.py — fetch + render\n\nThe primary tool. Pulls a dashboard via the dashboards API, which already returns each tile's *cached computed result* alongside the definition — so a single GET gives you both definitions and numbers. No HogQL execution needed.\n\n```bash\ncd packages\u002Fglass-box\nuv run python scripts\u002Finspect_posthog_dashboard.py --env \u003Cenv> --dashboard-id \u003Cid>\n```\n\nWrites:\n\n- `docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.md` — reviewable summary with HogQL results as markdown tables, Trends as per-series tables, Funnels as step-count tables. Definitions in collapsed `\u003Cdetails>` blocks.\n- `docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.json` — raw API response. Source of truth when extracting specific values; `result` field on each insight contains the cached numbers.\n\nFlags:\n\n- `--env \u003Clocal|dev|tux|prod>` (required)\n- `--dashboard-id \u003Cint>` (required)\n- `--out \u003Cpath>` — override default md path\n- `--no-json` — skip the `.json` sidecar (don't usually do this; the JSON is needed for value extraction)\n- `--no-results` — definitions only, faster, smaller. Use for a sanity check before a full snapshot.\n- `--stdout` — print to stdout instead of writing files. Use for quick eyeballing.\n\n### duplicate_posthog_dashboard.py — clone across environments\n\nRecreates a dashboard (with all insight tiles) in a different PostHog project. Used to promote tux dashboards to prod, or to seed a new project. Idempotent — skips if a dashboard with the same name already exists in the target.\n\n```bash\ncd packages\u002Fglass-box\nuv run python scripts\u002Fduplicate_posthog_dashboard.py \\\n    --source \u003Cenv> --target \u003Cenv> --dashboard-id \u003Cid> [--target-name \"...\"] [--dry-run]\n```\n\nLimitations:\n\n- Text tiles are skipped (warned).\n- Tile layout is not replayed; PostHog falls back to default grid.\n- Cross-project duplication recreates resources; the source dashboard is not modified.\n\n### What does NOT exist (yet — propose adding when needed)\n\n- A \"list dashboards in env X\" command. Use the PostHog UI for discovery.\n- A \"search dashboards by name\" command. Same.\n- A \"delete dashboard\" command. Use the PostHog UI; investigation dashboards stay around.\n- A direct HogQL execution helper for ad-hoc queries against a dashboard's underlying data. The `PostHogClient` in `packages\u002Fglass-box\u002Freplay\u002Futils\u002Fposthog_client.py` has a `.query(hogql)` method — use it for one-off questions, not for tile data (tile data is already cached in the dashboard JSON).\n\n## The standard workflows\n\n### Workflow A — User gives Claude a new dashboard ID\n\n1. **Run the inspector.** `uv run python scripts\u002Finspect_posthog_dashboard.py --env \u003Cenv> --dashboard-id \u003Cid>` from `packages\u002Fglass-box`.\n2. **Read the snapshot.** Open `docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.md` and skim. Note the dashboard name, tile count, and which spec section it likely belongs to.\n3. **Identify the topic.** Look at the dashboard name and tile content. Match against §1 of `posthog-insights-progress.md`. If the dashboard maps to an existing topic (`llm-cost`, `activation`, `monetization`, `tracking-quality`, …), use that topic folder. If it doesn't, create a new topic folder under `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002F\u003Ctopic>\u002F` with a `README.md` based on an existing one.\n4. **Determine the report number.** Look in the topic folder for the highest existing `NNN-*.md`. The new report is `NNN+1`. The first report in any chain is always `001-baseline.md`.\n5. **Write the report.** Copy `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002F_TEMPLATE.md` into the new file, fill in YAML frontmatter, then walk each tile and write findings. The frontmatter `parent_report` is `none` for a baseline; it's the path to the previous report when a new one supersedes or extends it.\n6. **Update the topic README.** Add a row to its \"Reports\" table; update the rolled-up \"Open action items\" with new P0\u002FP1 entries.\n7. **Update the status board.** Edit `posthog-insights-progress.md` §1 — update the row for the topic with the new report link, status, and P0\u002FP1 counts.\n8. **If a finding implies a cross-cutting gap** (instrumentation that affects multiple dashboards), add a row to `posthog-insights-progress.md` §2 *Cross-cutting instrumentation gaps*.\n\n### Workflow B — User asks for a follow-up investigation\n\nThe user references a finding (e.g. \"investigate F3 from llm-cost\u002F001\") or asks to \"spawn a deeper look at X.\"\n\n1. **Decide whether the investigation needs a new dashboard or just code reading.** Code reading is cheaper — start there. Only spawn a dashboard if the question can't be answered from the code or existing snapshot.\n2. **If code reading suffices:** write a new numbered report in the same topic folder. Set `parent_report` to the originating report. Walk the code, document findings, propose actions. No new dashboard ID.\n3. **If a new dashboard is needed:** ask PostHog AI to build it (use the spec doc's conventions block + a topic-specific prompt), wait for the user to provide the new dashboard ID, then run Workflow A. The new report's `parent_report` is the originating report.\n4. **Update the parent report's \"Children\" section** to link to the new report.\n5. **Update the topic README's investigation map** — add the new report and any branches.\n\n### Workflow C — Dashboard revision applied\n\nThe user pasted Claude's revision prompt back into PostHog AI; the dashboard now has updated tiles.\n\n1. **Re-snapshot.** Same dashboard ID. The inspector overwrites the previous snapshot — that's fine; the prior analysis is preserved in the report.\n2. **Decide: new report or update existing?**\n\n- If the revision *materially changes the numbers* (e.g. F1 in LLM cost\u002F001 was a 5x understated headline — fixing it is material) → write a new report. Mark the previous report `superseded` in its frontmatter and add the new path to its `Children` section.\n- If the revision is cosmetic (axis label, decimal places) → update the existing report's \"Decisions taken\" section and bump the snapshot reference. Don't create a new report.\n\n3. **Update the topic README** and status board accordingly.\n\n### Workflow D — User asks to build a new dashboard for a topic that has no spec yet\n\n1. **Don't invent a spec out of thin air.** Push back to the user: \"What's the question this dashboard should answer?\" Get to a specific business question.\n2. **Draft the §X spec section in `posthog-insights-scope.md`.** Use the existing §1.1–§1.4 as templates. Property reference, conventions block, exact tile prompt.\n3. **Have the user paste the prompt into PostHog AI** and provide the resulting dashboard ID.\n4. **Then run Workflow A** to write the baseline report.\n\n### Workflow E — Promoting a dashboard tux → prod\n\n1. **Confirm the dashboard is signed off** — its latest report is `resolved` or all P0 items are closed.\n2. **Run the duplicator** with `--dry-run` first to see the plan.\n3. **Run for real.** Note the new prod dashboard ID returned in the output.\n4. **Update the topic README** to record both IDs (active = prod, superseded = tux).\n5. **Re-snapshot the new prod dashboard** to capture its initial state. The first prod snapshot may have empty data because of ingestion lag — that's fine.\n\n## How to extract specific values from a snapshot JSON\n\nWhen you need to compute something across tiles (e.g. \"are Tile 18 and Tile 13 reporting the same total?\"), don't re-render the markdown — go straight to the JSON.\n\n```python\nimport json\nd = json.load(open('docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.json'))\n\n# Per tile:\nfor tile in d['tiles']:\n    insight = tile.get('insight') or {}\n    name = insight.get('name')\n    cols = insight.get('columns')        # for HogQL tiles\n    result = insight.get('result')       # for HogQL: list[list]; for Trends: list[dict]\n    last_refresh = insight.get('last_refresh')\n    src_kind = insight.get('query', {}).get('source', {}).get('kind')\n```\n\nFor HogQL tiles, `result` is a list of rows; `columns` gives column names. For TrendsQuery tiles, `result` is a list of series dicts each with `data`, `labels`, `days`, `count`, `aggregated_value`, `breakdown_value`. For FunnelsQuery, the structure is similar but step counts live in `count`.\n\n## The report template — what each section is for\n\nThe full template is at `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002F_TEMPLATE.md`. Sections in priority order:\n\n| Section | Job |\n| --- | --- |\n| YAML frontmatter | Machine-readable status, parent\u002Fchild links, dashboard ID, env. |\n| TL;DR | 2–3 sentences. The single conclusion. |\n| Headline numbers | The 4–8 numbers that drive decisions. Not the full data dump. |\n| Findings | Numbered (`F1`, `F2`, …) so other reports can reference them. Each has *what \u002F why \u002F confidence \u002F source tile*. |\n| Hypotheses | For medium- or low-confidence findings — list candidates and what would discriminate. |\n| Actions | Code changes \u002F dashboard revisions \u002F new investigations \u002F spec updates. Each with `[P0\u002FM]` priority + effort tags. PostHog AI revisions include the exact prompt to paste. |\n| Decisions taken | Append-only log. Useful when re-reading the chain. |\n| Open questions | Things that need more data; if a question seeds a new investigation, link to its report. |\n| Children | Reports spawned from this one. |\n\n## Common findings patterns and what they imply\n\nThese recur often enough to memorise.\n\n| Pattern | What it usually means | Default action |\n| --- | --- | --- |\n| A breakdown chart shows only `$$_posthog_breakdown_null_$$` and `$$_posthog_breakdown_other_$$` | Wrong breakdown property name, or the property is missing on most events | Verify property name in the JSON; fix in PostHog AI; if still broken, fall back to a HogQL table |\n| Headline aggregate disagrees with a HogQL sum of the same data | TrendsQuery `interval` is set to a too-large bucket (`month` on `-30d` collapses to current month) | Change interval to `day` or omit |\n| A HogQL tile coalesces a value to `'unknown'` and 100% of rows show `unknown` | The aliased property isn't being emitted at all (not just missing on some events) | Code-side fix on the OTel\u002Fevent emission path; the dashboard is doing what it should |\n| `$ai_generation` event has `distinct_id == $ai_trace_id` | Anonymous LLM call — `context.userId` wasn't passed to `buildExperimentalTelemetry` | Plumb the user id; usually a `withOperation` or middleware gap |\n| A typed event has zero call sites in apps but is in the catalog | Catalog drift — type was speculative or replaced. Decide retire vs wire up. | Update events inventory; either retire the type or implement |\n\n## Cross-references\n\n- Property reference for `$ai_generation` events: `docs\u002Farchitecture\u002Fobservability.md` §2 + `apps\u002Fai\u002Fsrc\u002Fcommon\u002Faisdk\u002Fsdk.ts` `buildExperimentalTelemetry()`.\n- Typed catalog: `packages\u002Fanalytics\u002Fsrc\u002Fevent-types.ts` (source of truth) + `docs\u002Farchitecture\u002Fposthog-events-inventory.md` (status of each).\n- Cost-emission migration debt: `gen_ai.cost.total_usd` (horde) vs `gen_ai.cost.total_tokens` (apps\u002Fai legacy, value is in USD). Tracked in `posthog-insights-scope.md` §1.4 conventions.\n- Skills you may invoke alongside this one: `hamster-analytics` (for instrumentation patterns when a fix involves adding events), `glass-box` (for replay-based investigation against the same PostHog data).\n\n## Anti-patterns\n\n- **Editing an issued report retroactively to fix a finding.** Append a new report or note in \"Decisions taken.\" Never rewrite the analysis.\n- **Putting raw data tables in `posthog-insights-progress.md`.** That doc is a status board only.\n- **Asking PostHog AI to build a dashboard without writing the spec section first.** Push the user back to the spec.\n- **Re-running the inspector and committing the snapshot when no analysis was done.** Snapshots are point-in-time; commit them only as part of a report.\n- **Skipping the topic README update when adding a report.** The README is the chain index — out of date, the navigation breaks.\n","# hamster-posthog-dashboards\n\nThis skill is the contract between Claude and the PostHog dashboard analysis system in Hamster Studio. When the user references a dashboard ID, asks to \"review,\" \"investigate,\" \"build,\" \"duplicate,\" or \"compare\" a dashboard, or asks to spawn a follow-up analysis, follow the patterns below.\n\n## When to invoke\n\n- \"Review dashboard `\u003Cid>`\" \u002F \"look at dashboard `\u003Cid>`\" \u002F \"what's in `\u003Cid>`?\"\n- \"Pull data from `\u003Cid>`\" \u002F \"compare against the spec\" \u002F \"is this dashboard right?\"\n- \"Investigate `\u003Cfinding>` from the LLM cost dashboard\"\n- \"Duplicate dashboard `\u003Cid>` to dev\" \u002F \"promote this dashboard to prod\"\n- \"Build a new dashboard for `\u003Ctopic>`\"\n- \"What's our LLM cost looking like?\" (implies pulling current data + writing\u002Fupdating a report)\n\n## When NOT to invoke\n\n- The user is talking about Mixpanel or Segment dashboards — this skill is PostHog-specific.\n- The user is asking about analytics *event instrumentation* in code (use `hamster-analytics` instead).\n- The user wants raw event-level data for one user to debug a bug — use the glass-box `PostHogClient` directly via `packages\u002Fglass-box\u002Freplay\u002Futils\u002Fposthog_client.py` rather than going through this skill's report workflow.\n\n## The doc structure (read before doing anything)\n\nFive surfaces, each with one job:\n\n| Surface | Purpose | Path |\n| --- | --- | --- |\n| Spec | What dashboards we want, with PostHog AI prompts | `docs\u002Farchitecture\u002Fposthog-insights-scope.md` |\n| Inventory | Typed catalog + drift | `docs\u002Farchitecture\u002Fposthog-events-inventory.md` |\n| Status board | One row per dashboard with link to latest report | `docs\u002Farchitecture\u002Fposthog-insights-progress.md` |\n| Snapshots | Raw data — definitions + cached results from PostHog | `docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.{md,json}` |\n| Reports | **Distilled analysis chains, per topic** | `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002F\u003Ctopic>\u002F\u003CNNN>-\u003Cslug>.md` |\n\n**Never put numbers or per-tile reviews in the spec or status board.** They go in reports.\n**Never edit a snapshot file by hand.** They are written by the inspector script.\n**Never edit a report after it has been issued (status `action-items-issued` or later).** Write a new numbered report instead. Reports are append-only.\n\nThe full structure plus templates is documented in `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002FREADME.md` and the topic READMEs.\n\n## The scripts\n\nBoth live in `packages\u002Fglass-box\u002Fscripts\u002F` and use `.env.\u003Cenv>` files populated by `pnpm get-env-qa`. Each needs `POSTHOG_DASHBOARD_API_KEY` (personal API key with `dashboard:read`, `insight:read` minimum; `dashboard:write` and `insight:write` for duplication) and `POSTHOG_PROJECT_ID` (or `POSTHOG_PROD_PROJECT_ID`).\n\n### inspect_posthog_dashboard.py — fetch + render\n\nThe primary tool. Pulls a dashboard via the dashboards API, which already returns each tile's *cached computed result* alongside the definition — so a single GET gives you both definitions and numbers. No HogQL execution needed.\n\n```bash\ncd packages\u002Fglass-box\nuv run python scripts\u002Finspect_posthog_dashboard.py --env \u003Cenv> --dashboard-id \u003Cid>\n```\n\nWrites:\n\n- `docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.md` — reviewable summary with HogQL results as markdown tables, Trends as per-series tables, Funnels as step-count tables. Definitions in collapsed `\u003Cdetails>` blocks.\n- `docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.json` — raw API response. Source of truth when extracting specific values; `result` field on each insight contains the cached numbers.\n\nFlags:\n\n- `--env \u003Clocal|dev|tux|prod>` (required)\n- `--dashboard-id \u003Cint>` (required)\n- `--out \u003Cpath>` — override default md path\n- `--no-json` — skip the `.json` sidecar (don't usually do this; the JSON is needed for value extraction)\n- `--no-results` — definitions only, faster, smaller. Use for a sanity check before a full snapshot.\n- `--stdout` — print to stdout instead of writing files. Use for quick eyeballing.\n\n### duplicate_posthog_dashboard.py — clone across environments\n\nRecreates a dashboard (with all insight tiles) in a different PostHog project. Used to promote tux dashboards to prod, or to seed a new project. Idempotent — skips if a dashboard with the same name already exists in the target.\n\n```bash\ncd packages\u002Fglass-box\nuv run python scripts\u002Fduplicate_posthog_dashboard.py \\\n    --source \u003Cenv> --target \u003Cenv> --dashboard-id \u003Cid> [--target-name \"...\"] [--dry-run]\n```\n\nLimitations:\n\n- Text tiles are skipped (warned).\n- Tile layout is not replayed; PostHog falls back to default grid.\n- Cross-project duplication recreates resources; the source dashboard is not modified.\n\n### What does NOT exist (yet — propose adding when needed)\n\n- A \"list dashboards in env X\" command. Use the PostHog UI for discovery.\n- A \"search dashboards by name\" command. Same.\n- A \"delete dashboard\" command. Use the PostHog UI; investigation dashboards stay around.\n- A direct HogQL execution helper for ad-hoc queries against a dashboard's underlying data. The `PostHogClient` in `packages\u002Fglass-box\u002Freplay\u002Futils\u002Fposthog_client.py` has a `.query(hogql)` method — use it for one-off questions, not for tile data (tile data is already cached in the dashboard JSON).\n\n## The standard workflows\n\n### Workflow A — User gives Claude a new dashboard ID\n\n1. **Run the inspector.** `uv run python scripts\u002Finspect_posthog_dashboard.py --env \u003Cenv> --dashboard-id \u003Cid>` from `packages\u002Fglass-box`.\n2. **Read the snapshot.** Open `docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.md` and skim. Note the dashboard name, tile count, and which spec section it likely belongs to.\n3. **Identify the topic.** Look at the dashboard name and tile content. Match against §1 of `posthog-insights-progress.md`. If the dashboard maps to an existing topic (`llm-cost`, `activation`, `monetization`, `tracking-quality`, …), use that topic folder. If it doesn't, create a new topic folder under `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002F\u003Ctopic>\u002F` with a `README.md` based on an existing one.\n4. **Determine the report number.** Look in the topic folder for the highest existing `NNN-*.md`. The new report is `NNN+1`. The first report in any chain is always `001-baseline.md`.\n5. **Write the report.** Copy `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002F_TEMPLATE.md` into the new file, fill in YAML frontmatter, then walk each tile and write findings. The frontmatter `parent_report` is `none` for a baseline; it's the path to the previous report when a new one supersedes or extends it.\n6. **Update the topic README.** Add a row to its \"Reports\" table; update the rolled-up \"Open action items\" with new P0\u002FP1 entries.\n7. **Update the status board.** Edit `posthog-insights-progress.md` §1 — update the row for the topic with the new report link, status, and P0\u002FP1 counts.\n8. **If a finding implies a cross-cutting gap** (instrumentation that affects multiple dashboards), add a row to `posthog-insights-progress.md` §2 *Cross-cutting instrumentation gaps*.\n\n### Workflow B — User asks for a follow-up investigation\n\nThe user references a finding (e.g. \"investigate F3 from llm-cost\u002F001\") or asks to \"spawn a deeper look at X.\"\n\n1. **Decide whether the investigation needs a new dashboard or just code reading.** Code reading is cheaper — start there. Only spawn a dashboard if the question can't be answered from the code or existing snapshot.\n2. **If code reading suffices:** write a new numbered report in the same topic folder. Set `parent_report` to the originating report. Walk the code, document findings, propose actions. No new dashboard ID.\n3. **If a new dashboard is needed:** ask PostHog AI to build it (use the spec doc's conventions block + a topic-specific prompt), wait for the user to provide the new dashboard ID, then run Workflow A. The new report's `parent_report` is the originating report.\n4. **Update the parent report's \"Children\" section** to link to the new report.\n5. **Update the topic README's investigation map** — add the new report and any branches.\n\n### Workflow C — Dashboard revision applied\n\nThe user pasted Claude's revision prompt back into PostHog AI; the dashboard now has updated tiles.\n\n1. **Re-snapshot.** Same dashboard ID. The inspector overwrites the previous snapshot — that's fine; the prior analysis is preserved in the report.\n2. **Decide: new report or update existing?**\n\n- If the revision *materially changes the numbers* (e.g. F1 in LLM cost\u002F001 was a 5x understated headline — fixing it is material) → write a new report. Mark the previous report `superseded` in its frontmatter and add the new path to its `Children` section.\n- If the revision is cosmetic (axis label, decimal places) → update the existing report's \"Decisions taken\" section and bump the snapshot reference. Don't create a new report.\n\n3. **Update the topic README** and status board accordingly.\n\n### Workflow D — User asks to build a new dashboard for a topic that has no spec yet\n\n1. **Don't invent a spec out of thin air.** Push back to the user: \"What's the question this dashboard should answer?\" Get to a specific business question.\n2. **Draft the §X spec section in `posthog-insights-scope.md`.** Use the existing §1.1–§1.4 as templates. Property reference, conventions block, exact tile prompt.\n3. **Have the user paste the prompt into PostHog AI** and provide the resulting dashboard ID.\n4. **Then run Workflow A** to write the baseline report.\n\n### Workflow E — Promoting a dashboard tux → prod\n\n1. **Confirm the dashboard is signed off** — its latest report is `resolved` or all P0 items are closed.\n2. **Run the duplicator** with `--dry-run` first to see the plan.\n3. **Run for real.** Note the new prod dashboard ID returned in the output.\n4. **Update the topic README** to record both IDs (active = prod, superseded = tux).\n5. **Re-snapshot the new prod dashboard** to capture its initial state. The first prod snapshot may have empty data because of ingestion lag — that's fine.\n\n## How to extract specific values from a snapshot JSON\n\nWhen you need to compute something across tiles (e.g. \"are Tile 18 and Tile 13 reporting the same total?\"), don't re-render the markdown — go straight to the JSON.\n\n```python\nimport json\nd = json.load(open('docs\u002Farchitecture\u002Fposthog-snapshots\u002F\u003Cid>.json'))\n\n# Per tile:\nfor tile in d['tiles']:\n    insight = tile.get('insight') or {}\n    name = insight.get('name')\n    cols = insight.get('columns')        # for HogQL tiles\n    result = insight.get('result')       # for HogQL: list[list]; for Trends: list[dict]\n    last_refresh = insight.get('last_refresh')\n    src_kind = insight.get('query', {}).get('source', {}).get('kind')\n```\n\nFor HogQL tiles, `result` is a list of rows; `columns` gives column names. For TrendsQuery tiles, `result` is a list of series dicts each with `data`, `labels`, `days`, `count`, `aggregated_value`, `breakdown_value`. For FunnelsQuery, the structure is similar but step counts live in `count`.\n\n## The report template — what each section is for\n\nThe full template is at `packages\u002Fglass-box\u002Fdata\u002Fposthog-reports\u002F_TEMPLATE.md`. Sections in priority order:\n\n| Section | Job |\n| --- | --- |\n| YAML frontmatter | Machine-readable status, parent\u002Fchild links, dashboard ID, env. |\n| TL;DR | 2–3 sentences. The single conclusion. |\n| Headline numbers | The 4–8 numbers that drive decisions. Not the full data dump. |\n| Findings | Numbered (`F1`, `F2`, …) so other reports can reference them. Each has *what \u002F why \u002F confidence \u002F source tile*. |\n| Hypotheses | For medium- or low-confidence findings — list candidates and what would discriminate. |\n| Actions | Code changes \u002F dashboard revisions \u002F new investigations \u002F spec updates. Each with `[P0\u002FM]` priority + effort tags. PostHog AI revisions include the exact prompt to paste. |\n| Decisions taken | Append-only log. Useful when re-reading the chain. |\n| Open questions | Things that need more data; if a question seeds a new investigation, link to its report. |\n| Children | Reports spawned from this one. |\n\n## Common findings patterns and what they imply\n\nThese recur often enough to memorise.\n\n| Pattern | What it usually means | Default action |\n| --- | --- | --- |\n| A breakdown chart shows only `$$_posthog_breakdown_null_$$` and `$$_posthog_breakdown_other_$$` | Wrong breakdown property name, or the property is missing on most events | Verify property name in the JSON; fix in PostHog AI; if still broken, fall back to a HogQL table |\n| Headline aggregate disagrees with a HogQL sum of the same data | TrendsQuery `interval` is set to a too-large bucket (`month` on `-30d` collapses to current month) | Change interval to `day` or omit |\n| A HogQL tile coalesces a value to `'unknown'` and 100% of rows show `unknown` | The aliased property isn't being emitted at all (not just missing on some events) | Code-side fix on the OTel\u002Fevent emission path; the dashboard is doing what it should |\n| `$ai_generation` event has `distinct_id == $ai_trace_id` | Anonymous LLM call — `context.userId` wasn't passed to `buildExperimentalTelemetry` | Plumb the user id; usually a `withOperation` or middleware gap |\n| A typed event has zero call sites in apps but is in the catalog | Catalog drift — type was speculative or replaced. Decide retire vs wire up. | Update events inventory; either retire the type or implement |\n\n## Cross-references\n\n- Property reference for `$ai_generation` events: `docs\u002Farchitecture\u002Fobservability.md` §2 + `apps\u002Fai\u002Fsrc\u002Fcommon\u002Faisdk\u002Fsdk.ts` `buildExperimentalTelemetry()`.\n- Typed catalog: `packages\u002Fanalytics\u002Fsrc\u002Fevent-types.ts` (source of truth) + `docs\u002Farchitecture\u002Fposthog-events-inventory.md` (status of each).\n- Cost-emission migration debt: `gen_ai.cost.total_usd` (horde) vs `gen_ai.cost.total_tokens` (apps\u002Fai legacy, value is in USD). Tracked in `posthog-insights-scope.md` §1.4 conventions.\n- Skills you may invoke alongside this one: `hamster-analytics` (for instrumentation patterns when a fix involves adding events), `glass-box` (for replay-based investigation against the same PostHog data).\n\n## Anti-patterns\n\n- **Editing an issued report retroactively to fix a finding.** Append a new report or note in \"Decisions taken.\" Never rewrite the analysis.\n- **Putting raw data tables in `posthog-insights-progress.md`.** That doc is a status board only.\n- **Asking PostHog AI to build a dashboard without writing the spec section first.** Push the user back to the spec.\n- **Re-running the inspector and committing the snapshot when no analysis was done.** Snapshots are point-in-time; commit them only as part of a report.\n- **Skipping the topic README update when adding a report.** The README is the chain index — out of date, the navigation breaks.\n",{"name":5,"version":24,"description":7},"1.0.0","main","fe3bb1476c3ec23d8a366eac0fa8cd9f0852360a","skills\u002F.experimental\u002Fhamster-posthog-dashboards",0,"https:\u002F\u002Fgithub.com\u002Fgethamster\u002Fskills","https:\u002F\u002Fgithub.com\u002Fgethamster","https:\u002F\u002Ftryhamster.com","We're building the AI-native future of work, unlocking the promised acceleration for your whole team, from idea to impact.","2026-11-05 11:33:33",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add gethamster\u002Fskills --skill hamster-posthog-dashboards",{"tool":40,"command":41},"bunx","bunx skills add gethamster\u002Fskills --skill hamster-posthog-dashboards",{"tool":43,"command":44},"pnpm","pnpm dlx skills add gethamster\u002Fskills --skill hamster-posthog-dashboards","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgethamster\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002F.experimental\u002Fhamster-posthog-dashboards\u002FSKILL.md",true,[],[49,56,63,70,77,84],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7B5MWYW0KE251276S56KQDZ","writing-waterfall-requirements-documents","Write a waterfall requirements document: elicit, structure and review testable, traceable requirements, then baseline the specification before design.","https:\u002F\u002Fgithub.com\u002Fgethamster\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-waterfall-requirements-documents\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7B5MRCXWWPKREPB1CHQ7H90","writing-vision-and-values-statements","Write a V2MOM vision a reader can test and a ranked list of values that settles real tradeoffs, so the rest of the document has a clear anchor.","https:\u002F\u002Fgithub.com\u002Fgethamster\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-vision-and-values-statements\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7B5MKH2CH22YZAHQW3080VQ","writing-system-prompts-for-claude","Write Claude prompts and CLAUDE.md files that supply exact inputs, scope the task, and define done so the first attempt can be checked.","https:\u002F\u002Fgithub.com\u002Fgethamster\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-system-prompts-for-claude\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M7B5ME1Y3X9RNRKP5HKHKACZ","writing-page-specific-website-copy","Website copywriting by page type: write homepage, landing page, pricing page and feature page copy that fits each page's visitor and single job.","https:\u002F\u002Fgithub.com\u002Fgethamster\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-page-specific-website-copy\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7B5M8MQNM8MN8PYH6BVWJ2B","writing-internal-press-releases","How to write an internal press release: the one-page working backwards press release that opens a PR\u002FFAQ document before anything is built.","https:\u002F\u002Fgithub.com\u002Fgethamster\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-internal-press-releases\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7B5M3P3YH1XF37R8PWXXSBK","writing-email-sequences-that-sell","Email sequence copywriting for nurture and sales: give each email one job, write clear subject lines, and close with one specific call to action.","https:\u002F\u002Fgithub.com\u002Fgethamster\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-email-sequences-that-sell\u002FSKILL.md",[],[]]