auto-alarms

name	auto-alarms
description	Create CloudWatch alarms and SNS subscription for AI automation monitoring. Creates 4 alarms (DLQ depth, WI-Router errors, PR-Router errors, throttles) and subscribes an email address to alerts. Reads config from .ai/automation/infra.json.
when_to_use	Use when setting up CloudWatch monitoring for AI automation, when the user says 'create alarms', 'set up monitoring', 'configure alerts', or 'add SNS notifications' for the automation pipeline.
argument-hint	[--email [e-mail]]

You create CloudWatch alarms and subscribe an email address to alerts. Wraps lambda/cloudwatch/setup-alarms.sh with audit logging.

0. Prerequisites

Read .ai/automation/infra.json. Check automationProfile:

• If consumer (or legacy pr-only/pr-delegation): "This repo uses the consumer profile — CloudWatch alarms are managed by the hub project. Do NOT configure alarms from this repo." STOP.

source .ai/lib/audit.sh
export AUDIT_LOG_PREFIX=infra

Confirm monitoring config from infra.json:

• monitoring.snsTopic.name — SNS topic name (<prefix>-alerts)
• region

1. Collect Email

If user passed --email <address>, use it. Otherwise ask:

Alert email address? CloudWatch alarms will notify this email for DLQ depth, Lambda errors, and throttles. You'll need to confirm the subscription in your email.

2. Run Setup Script

cd .ai/automation
bash lambda/cloudwatch/setup-alarms.sh --email "<email>"

The script:

1. Creates the SNS topic <prefix>-alerts (idempotent)
2. Subscribes the email to the topic
3. Creates 4 CloudWatch alarms (reads definitions from lambda/cloudwatch/alarms.json, prefixes with resource prefix from infra.json)
4. Links each alarm to the SNS topic

Report the script's output.

3. Update infra.json

After the script runs, the SNS topic ARN is returned. Update infra.json:

• monitoring.snsTopic.arn → the created/retrieved ARN

4. Summary Report

## CloudWatch Monitoring Configured

**SNS topic:** <prefix>-alerts
**Alert email:** <email> (confirm subscription in your inbox)

| Alarm | Trigger | Severity |
|-------|---------|----------|
| <prefix>-dlq-depth | DLQ > 5 messages | Warning |
| <prefix>-lambda-errors-wi-router | WI-Router Lambda errors > 3/hour | Critical |
| <prefix>-lambda-errors-pr-router | PR-Router Lambda errors > 3/hour | Critical |
| <prefix>-lambda-throttles | Any Lambda throttled | Warning |

**infra.json** updated with SNS ARN.
**Audit log:** `.ai/logs/infra.<week>.jsonl`

### Next step
`/auto-test --dryRun` — Verify end-to-end (local dry run)

### Operational commands
- `/auto-status` — Current DLQ depth, token budget, rate limits
- `/auto-doctor` — Full health check
- See `docs/runbook.md` for alert response procedures

Success Criteria

• CloudWatch alarms created for all 4 metrics (DLQ depth, WI-Router errors, PR-Router errors, throttles)
• SNS email subscription created — confirmation email sent to the provided address
• infra.json updated with SNS topic ARN

Examples

1. /auto-alarms — Reads infra.json for resource prefix and SNS topic ARN. Creates 4 CloudWatch alarms: DLQ depth > 0, WI-Router errors > 5/min, PR-Router errors > 5/min, Lambda throttles > 0. Subscribes the configured email to the SNS topic. Reminds user to confirm the SNS subscription via email.

2. /auto-alarms [e-mail] — Creates all 4 alarms and subscribes [e-mail] to the SNS alert topic. Reports each alarm name and threshold. Prints reminder to check inbox for subscription confirmation.

3. /auto-alarms (re-run, alarms exist) — put-metric-alarm is idempotent — overwrites existing alarms with current thresholds. SNS create-topic returns the existing topic ARN. subscribe is also idempotent if the email is already subscribed. Reports all alarms as configured.

Troubleshooting

• "SNS subscription confirmation not received" Cause: The confirmation email may have gone to spam, or the email address was incorrect. Fix: Check the spam folder. If not found, re-run /auto-alarms with the correct email — SNS will resend the confirmation. The subscription won't be active until confirmed.

• Alarms not triggering despite errors Cause: The alarm metric namespace or dimensions don't match the Lambda function names. Fix: Verify that the function names in infra.json match the actual Lambda function names in AWS. The alarms use FunctionName dimension to filter metrics.

• "Access denied" when creating alarms Cause: The AWS credentials lack CloudWatch or SNS permissions. Fix: Ensure the IAM user has cloudwatch:PutMetricAlarm, sns:CreateTopic, and sns:Subscribe permissions.

Rules

• Always source audit.sh first — setup-alarms.sh uses aws_resource wrapper
• Email confirmation required — remind user to check inbox for SNS subscription confirmation
• Idempotent — SNS create-topic is idempotent; alarms are overwritten if they exist (put-metric-alarm is idempotent)