Agent skill · posthog
announcing-behavior-changes
Decides whether a behavior-changing fix needs an in-app notice, then builds one that reaches only the affected users and can be removed later. Use when a change alters what an existing user sees without them doing anything — a metric moves, a chart shifts, a count drops, a date range resolves differently, a matcher matches differently — and when adding, reviewing, or removing such a notice. Trigger terms: behavior change, breaking change, semantics change, "results may differ", change notice, deprecation banner, migration banner. Carries the gate (narrow to the affected users with a tested predicate, or do not ship a notice at all), the pattern from `SqlInsightDateFilterNotice`, where to anchor the notice, and the flag-based removal path. Not for new features (use the changelog), not for permanent per-object warnings computed by the backend, and not for the wording itself (see `/writing-user-facing-copy`).
What it needs
About 6k tokens when loaded.
What this skill does
Announcing behavior changes Some fixes correct wrong behavior but change what a user sees. The number moves, the chart shifts, the count drops. Nothing is broken, but from the user's side it is indistinguishable from a regression, and they have no way to find out why. An in-app change notice closes that gap: it appears where the user sees the different result, says what changed, and then goes away. The reference implementation is frontend/src/queries/nodes/DataVisualization/Components/SqlInsightDateFilterNotice.tsx, shipped in commit 76f2905222a alongside the backend change it explains. Read it before writing a new one — it is 60 lines and it is the whole pattern. First: does this change need a notice? Most changes do not. A notice that fires for people it does not concern is worse than no notice, because it teaches everyone to dismiss banners without reading them. Ship one only when all four hold. 1. A user who does nothing sees something different. Not a new feature, not a change they opted into behind a flag. 2. They cannot work out why from the screen. If the UI already explains it, the UI is the notice. 3. The difference is big enough to notice. A rounding change in the fourth decimal is not. 4. You can identify who is affected, in code. See below — this is the one that usually fails. The narrowing test Write the predicate first. If you cannot express "this user is affected" as a function of state the client already has, you are about to show a banner to everyone about something that concerns a minority. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills posthog/announcing-behavior-changes