Adding Product Alerting
Developmentadding-product-alertingAdding Product Alerting is an Agent Skill for development published in the PostHog/posthog repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Recommended repo-engineering guide when adding alerting to a PostHog product or extending the shared alerts platform. Routes lifecycle state machines, AlertPolicy, destinations, HogFunction dispatch, email, fixed-cadence and calendar scheduling, insight evaluation, the AlertWizard, and shared alert editor components. Use for product alert implementations, shared destination types, lifecycle or scheduling options, advanced alert settings, and platform alert infrastructure. Not for configuring alerts in an existing product.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/PostHog/posthog/blob/HEAD/.agents/skills/adding-product-alerting/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/adding-product-alerting, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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:
- Add platform alerting to a product by composing the shared lifecycle, destination, delivery, scheduling, email, and frontend primitives.
- Extend the alerts platform when a reusable capability, option, or advanced behavior belongs in shared infrastructure.
Route first
| Request | Path | Read |
|---|---|---|
| Add alerting to a product | Adopt | adopting-platform-alerting.md |
| Build or extend a product alert editor, destination UI, advanced options, or evaluation history | Frontend | frontend-alerting.md |
| Add a lifecycle rule, destination type, delivery behavior, schedule primitive, email capability, wizard option, or shared evaluation feature | Extend | extending-platform-alerting.md |
| Change behavior for one existing product | Adopt first | Keep it product-owned unless the behavior is reusable and backed by a real second use case |
| Understand ownership or choose the correct layer | Architecture | architecture.md |
| Configure or author an existing logs or error tracking alert | Out of scope | Use authoring-log-alerts or authoring-error-tracking-alerts |
| Add real-time in-app notifications | Out of scope | Use sending-notifications |
Platform invariants
Both paths must preserve these rules:
- Evaluation stays domain-specific. Products decide whether their data breached. The shared lifecycle consumes normalized
CheckInput. - One lifecycle machine. Reuse
common/alerting/state_machine.py; express real product differences throughAlertPolicy, not forks. - One product mutator. Every persisted
stateorconsecutive_failureswrite goes through the product adapter'sapply_outcome. - 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.
- Destinations are allowlisted. Shared support does not automatically expose a destination in every product.
- 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. - Shared code has no product branches.
common/alerting/stays pure Python. Reusable Django behavior belongs inproducts/alerts/backend/. - 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.
- 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
| Topic | Reference |
|---|---|
| Layer ownership, public contracts, and reference adopters | architecture.md |
| Add alerting to a product | adopting-platform-alerting.md |
| Extend shared alert infrastructure | extending-platform-alerting.md |
| Build the product alert frontend | frontend-alerting.md |