notifications

name	notifications
description	Use when creating, updating, reviewing, or debugging notifications, email, SMS, push messages, templates, delivery status, retries, user preferences, or notification security.

Notifications

Use this skill for safe and reliable notification flows.

Rules

• Follow the project’s existing notification pattern.
• Do not add a new email, SMS, push, queue, or template provider unless already used or explicitly requested.
• Keep notification sending outside critical request paths when the project supports background jobs.
• Use templates for reusable messages.
• Validate recipients and required template data.
• Avoid duplicate sends with idempotency when retries or webhooks are involved.
• Track delivery status when the project has a notification record model.
• Respect user notification preferences for non-critical messages.
• Always allow critical security, billing, and account notifications when required.
• Never log full emails, phone numbers, tokens, reset links, magic links, or private message content.
• Preserve existing response, error, logging, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing notification code, check existing patterns for:

• provider
• template system
• queue/background job usage
• delivery records
• retry behavior
• recipient validation
• user preferences
• logging/redaction
• test style

Implementation Checklist

• Identify the notification type and channel.
• Reuse existing service/provider/template helpers.
• Validate recipient and payload.
• Render message from the existing template pattern.
• Send immediately only if the project already does that safely.
• Prefer async/background sending when available.
• Make retries safe.
• Prevent duplicate delivery.
• Store delivery status if the project supports it.
• Mask recipient data in logs.
• Add or update relevant tests.

Security Checklist

• Do not expose secrets or provider keys.
• Do not log reset links, verification links, OTP codes, or magic links.
• Do not send sensitive content to an unverified recipient unless the project allows it.
• Do not let users send notifications to resources they do not own.
• Do not ignore opt-out preferences for marketing or non-critical messages.
• Keep critical notifications safe, minimal, and reliable.

Failure Handling

• Invalid recipient: fail safely and do not retry endlessly.
• Provider failure: retry only if safe and supported.
• Template missing: fail clearly.
• Duplicate request: skip or reuse existing delivery record.
• Rate limit: back off when the project supports it.
• Partial failure: record the failed channel without hiding the error.

Tests

Cover relevant paths:

• notification created or queued
• template renders correctly
• invalid recipient
• provider failure
• retry or duplicate prevention
• preference opt-out
• critical notification still allowed
• sensitive data not logged