mcpField
M
modifying-taxonomic-filter

modifying-taxonomic-filter

github.com/posthogDevelopment40.5k171 installsUpdated today
Repository

About modifying-taxonomic-filter

A development skill for changing PostHog's TaxonomicFilter, the picker for analytics and configuration entities. It provides evidence-based guardrails for legacy and rebuilt surfaces, telemetry contracts, testing, and change measurement.

Key features

  1. 01Evidence-led change guidance
  2. 02Legacy and rebuilt surface parity
  3. 03Telemetry contract safeguards
  4. 04Change-specific reference routing
  5. 05Testing and measurement checklist

Use cases

  1. 01Add or remove a filter group or tab
  2. 02Adjust search, recents, or ordering
  3. 03Investigate a reported picker bug
  4. 04Plan tests and metrics for a change

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/posthog/posthog --skill modifying-taxonomic-filter

After installing, type/modifying-taxonomic-filterin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
architecture.md
call-sites-and-blast-radius.md
common-pitfalls.md
contested-decisions.md
design-principles.md
evidence-sources.md
failure-modes.md
feature-inventory.md
measuring-changes.md
performance.md
product-reality.md
refreshing-product-reality.md
surfaces-and-mirroring.md
telemetry-contract.md
testing-patterns.md

Details

From the project README

Modifying the TaxonomicFilter

The TaxonomicFilter is the picker users hit to choose any "thing PostHog knows about": events, properties, actions, cohorts, groups. It is the on-ramp into almost every analytics, flags and replay configuration. Code lives in frontend/src/lib/components/TaxonomicFilter/.

This file is an index. Read it fully, then load only the references your change needs. The references hold the detail and the evidence.

Four guardrails

  1. Decide with evidence, not taste. Everyone who has worked on this picker has strong opinions, and some of them are wrong. Check a claim against product-reality and evidence-sources before acting on it, including claims in issues, Slack, or this skill.
  2. Demoting what users actually pick is a regression, even with every test green. Ordering, promotion, position-0 and default-tab changes need explicit human sign-off.
  3. Two surfaces, two implementations. The rebuild reimplements the legacy data layer. Most behavior changes land in both, or the arms diverge. See surfaces-and-mirroring.
  4. Telemetry is a public contract. Dashboards and replay scanners read these events. Never rename or repurpose a property silently. telemetryContract.test.ts fails when a capture call and the contract disagree, so update the contract in the same PR. See telemetry-contract.

The picture in five lines (refreshed 2026-10-15)

  • Most engaged legacy opens end in a selection (~85%), and most never touch a category tab (~96%).
  • The Suggested view carries about 70% of legacy selections. Just over half of those come from recents.
  • Position matters: ~52% of legacy picks are row 0, ~85% are in the top three.
  • The biggest failure is a category picked first, then a search that finds nothing. Most empty searches are the right word in the wrong tab.
  • Customers report broken UI and missing items far more than slowness.

Detail, windows and caveats: product-reality. These numbers are a snapshot. For current values, run the taxonomic_filter_* metrics in the PostHog data catalog (see refreshing-product-reality).

Route by what you are changing

You are changingRead first
Ordering, promotion, Suggested, default tabproduct-reality, design-principles, contested-decisions
Adding, removing or hiding a group or tabfeature-inventory, surfaces-and-mirroring, call-sites
Search, empty states, no-results recoveryfailure-modes, design-principles
Recents, pinning, remembered statecontested-decisions, design-principles
Loading, latency, pagination, errorsperformance, failure-modes
Telemetry or dashboardstelemetry-contract, measuring-changes
Any refactorarchitecture, common-pitfalls, testing-patterns
A bug report you can't reproducesurfaces-and-mirroring (confirm the surface first)
Deciding whether a change is worth itevidence-sources, measuring-changes

Working loop

  1. State the user problem. Which surface, which users, what goes wrong. Find it in the evidence, not only in the request. See evidence-sources.
  2. Size it. Use ratios from telemetry. A change that helps 0.1% of opens and risks the Suggested view is not worth it.
  3. Check the principles and contested decisions that apply. If your change reverses a documented decision, say so and bring evidence.
  4. Make the change in both surfaces, or say explicitly why not.
  5. Lock behavior with React Testing Library tests at the call sites you touched. Agents find this component confusing; RTL tests are the fastest guard. See testing-patterns.
  6. Decide how you will know it worked before merging. Ship ordering or default changes behind a flag with a metric and a guardrail. See measuring-changes.

Pre-change checklist

  • The user problem is linked to evidence (telemetry, replay, ticket)
  • Change mirrored across legacy and rebuild, or the gap is stated
  • Both surfaces tested if tabs or groups changed
  • Shared telemetry payloads still match across both emitters
  • Ordering, promotion, position-0 or default tab: human sign-off
  • Search or loading: plan boundary verified, optional requests don't delay results
  • A success metric and a guardrail metric are named
  • If you changed the facts, update product-reality
hogli test frontend/src/lib/components/TaxonomicFilter/

Keep this skill honest: if the data contradicts it, fix the skill in the same PR. Refresh numbers with refreshing-product-reality when they are older than about three months.

Comments

Markdown supported