/suggesting-path-cleaning-rules

name: suggesting-path-cleaning-rules
description: 'Runs and reasons about the automated AI health check that suggests path-cleaning rules for web-analytics teams. Use when asked to generate path-cleaning suggestions for a team or cohort, to run the suggestion check, to review/apply AI-suggested rules, to inspect path_cleaning_suggestions health issues, or to extend the suggestion pipeline. Covers the suggest_path_cleaning_rules management command, the path_cleaning_suggestions health check, the cohort gating (precompute teams), and how suggestions are validated against real paths before storage. For hand-authoring or applying rules directly, use managing-path-cleaning-rules instead.'

Suggesting path-cleaning rules

Many teams never configure path cleaning, so their Web analytics breakdowns fragment across thousands of near-identical URLs. This feature **proactively suggests** cleaning rules for the web-analytics precompute cohort: weekly, for each team, it samples real paths, asks the LLM for `{regex, alias}` rules, validates them against the team's own paths, and stores them for review.

It **only suggests** — it never auto-applies. Applying rewrites historical numbers in every cleaned chart, so that stays a human decision (the existing settings UI, or the `--apply` flag below after review). To hand-author or directly apply rules, use the `managing-path-cleaning-rules` skill.

Architecture

• **Core**: `products/web_analytics/backend/path_cleaning_suggestions/service.py`
• `sample_pathnames` / `count_distinct_pathnames` — top `$pathname` by views via HogQL.
• `call_llm_for_rules` — one-shot call through the LLM gateway

(`get_llm_client(product="web_analytics", team_id=...)`, model `WEB_ANALYTICS_PATH_CLEANING_SUGGESTIONS_MODEL`, default `claude-haiku-4-5`).

• `validate_and_annotate_rules` — compiles each regex with **re2** (the engine ClickHouse

`replaceRegexpAll` uses) and test-applies it to the sampled paths. Rules that don't compile or match nothing are dropped; survivors get a dense `order`, a `match_count`, and in-memory before/after `examples` (printed by the management command, never stored — health-issue payloads are readable with just `health_issue:read` and must not leak real paths). This is the skill's "test before saving" step, automated.

• `generate_suggestions_for_team` — orchestrates the above with gating (see below); pure

generation, no storage.

• `apply_suggestions_to_team` — **merges** rules into `path_cleaning_filters`, never overwrites

(dedupes by regex, continues `order`).

• **Storage**: a `path_cleaning_suggestions` **health issue** (`HealthIssue`, severity `info`) — no

dedicated model. One active issue per team (`hash_keys=[]`); `payload` carries `rules`, `model`, `sampled_path_count`, `distinct_path_count`. Applying (or hand-configuring rules) resolves the issue on the next check run; dismissal is the health-issue `dismissed` flag.

• **Schedule**: `PathCleaningSuggestionsCheck`

(`products/web_analytics/backend/temporal/health_checks/path_cleaning_suggestions.py`), a health check on the shared health-check framework, weekly (Mon 06:23 UTC), small sequential batches because each eligible team costs an LLM call. Teams with an existing active suggestion are re-emitted without a fresh LLM round trip.

• **Cohort**: `WEB_ANALYTICS_PATH_CLEANING_SUGGESTIONS_TEAM_IDS`, defaulting to the precompute

enrollment list `WEB_ANALYTICS_LAZY_PRECOMPUTE_TEAM_IDS`.

Gating (why a team is skipped)

`generate_suggestions_for_team` returns a status:

• `skipped_inactive` — team sent no `$pageview` within `visited_within_days` (default 30); we only

suggest for teams actively using web analytics. Bypass with `--ignore-visit-gate`.

• `skipped_configured` — team already has path cleaning rules (override with `include_configured`).
• `skipped_low_cardinality` — fewer distinct paths than `min_distinct_paths` (default 50); cleaning

adds no value, so we don't spend tokens.

• `skipped_no_paths` — no pageviews in the window.
• `generated` — rules produced (may be an empty list if paths are already clean; empty generations

are never stored, so they can't shadow an actionable suggestion).

• `error` — sampling/LLM failed; captured per-team, never aborts the cohort sweep.

How users see and apply suggestions

• **Settings banner**: `PathCleaningSuggestionsBanner` on `/settings/project#path_cleaning` shows the

latest `suggested` row as regex → alias previews with match counts; "Apply all" (project admins only) merges the rules, the close button dismisses. Driven by `pathCleaningSuggestionsLogic`.

• **Onboarding step**: `OnboardingWebAnalyticsPathCleaningStep` (stepKey `path_cleaning`) surfaces the

same banner during Web analytics onboarding.

• **API** (`products/web_analytics/backend/api/web_analytics_path_cleaning_suggestions.py`):

`POST /api/projects/:id/web_analytics_path_cleaning_suggestions/generate/` produces and stores a fresh suggestion on demand; `GET .../{issue_id}/preview/` applies the rules to a fresh sample of the team's top paths and returns before/after pairs (read scope, computed on demand, never stored — this backs the banner's "Preview on your paths" modal); `POST .../{issue_id}/apply/` merges the rules and resolves the issue (project admin only — the same gate the team API puts on `path_cleaning_filters`). Listing and dismissing go through the generic health-issues API (`GET /api/projects/:id/health_issues/?kind=path_cleaning_suggestions&status=active&dismissed=false`, `PATCH .../health_issues/{id}/` with `{"dismissed": true}`).

• **Health page**: the check renders on `/web/health` alongside the other web-analytics checks, with

remediation guidance for humans and agents.

• **PostHog AI (Max)**: generate/apply are exposed as MCP tools in

`products/web_analytics/mcp/tools.yaml` (`web-analytics-path-cleaning-suggestions-{generate,apply}`), so a user can ask Max to sugg