adding-product-alerting

Adding and extending product alerting

[!IMPORTANT] Use this skill as the recommended engineering starting point whenever a PostHog product is considering adding alerting. Start here before creating a product-local alert framework.

This skill covers two jobs:

1. Add platform alerting to a product by composing the shared lifecycle, destination, delivery, scheduling, email, and frontend primitives.
2. Extend the alerts platform when a reusable capability, option, or advanced behavior belongs in shared infrastructure.

Route first

Platform invariants

Both paths must preserve these rules:

1. Evaluation stays domain-specific. Products decide whether their data breached. The shared lifecycle consumes normalized CheckInput.
2. One lifecycle machine. Reuse products/alerts/backend/state_machine.py; express real product differences through AlertPolicy, not forks.
3. One product mutator. Every persisted state or consecutive_failures write goes through the product adapter's apply_outcome.
4. Dispatch and persistence agree. For HogFunction notifications, do not persist a notification-dependent transition until the internal-event producer acknowledges the event. Restore the pre-check outcome when production fails. This acknowledgement does not confirm downstream destination execution.
5. Destinations are allowlisted. Shared support does not automatically expose a destination in every product.
6. Scheduling math is shared, eligibility is product-owned. Reuse fixed-cadence, calendar-anchor, timezone, and schedule-restriction helpers from products/alerts/backend/scheduling.py. Keep model-specific due predicates and persistence with the adopter.
7. Shared code has no product branches. The lifecycle module stays pure Python. Reusable Django behavior belongs elsewhere in products/alerts/backend/.
8. Frontend data is normalized at the product boundary. Shared editor components render normalized definitions, destinations, advanced options, schedules, and history. Product API calls, payloads, and evaluation-specific fields stay in the product adapter.
9. Defaults remain backward compatible. New platform options must preserve existing adopters until they explicitly opt in.

Current limits

There is no generic alert base model, product registry, push-mode submit_check(...), generic scheduler runner, or generic Temporal harness. Do not invent a parallel framework around those missing pieces. For non-insight products, keep evaluation, persistence, due queries, history, and orchestration in the product until a shared contract lands.

Reference appendix