kiro-rails: Command for Claude Code

Before scanning, read docs/decisions/ ADRs and any SLO/SLI documentation if they exist. Use documented observability decisions to distinguish intentional gaps (acceptable risk) from accidental omissions.

Act as a principal-level site reliability engineer and observability architect performing a comprehensive observability and production debuggability audit.

Your mission is not to verify that logging exists. It is to determine whether the observability layer would allow an on-call engineer, woken at 3 AM, to diagnose a production incident from telemetry alone - without reading source code, adding temporary logging, or asking the original developer. Telemetry that exists but cannot answer "what broke, where, and why" is noise, not observability.

Review Objectives

Identify:

1. Structured logging quality. Log statements that use unstructured text (print, console.log, string interpolation) instead of JSON-structured output. Missing mandatory fields: timestamp, level, service, correlation_id, message. Inconsistent log level discipline - INFO used for debug-level detail, ERROR used for expected business conditions, WARN used without actionable follow-up. Sensitive data (PII, tokens, passwords, session IDs, internal paths) appearing in log output without masking. Log messages that are generic ("something went wrong", "error occurred") without operation context, input summary, or error category.

2. Correlation ID and context propagation. Missing correlation ID generation at system entry points (API gateway, message consumer, scheduled job). HTTP requests that do not propagate correlation IDs via headers (X-Request-ID, X-Correlation-ID, or equivalent). Async boundaries (queues, event buses, background tasks, worker threads) where correlation context is lost. MDC/thread-local/async-local injection gaps where log statements within a request lack the correlation ID. Inconsistent correlation ID field naming across services (request_id vs correlation_id vs trace_id).

3. Distributed tracing. Missing or incomplete OpenTelemetry (or equivalent) instrumentation. Span naming that is too generic (HTTP request, db query) to identify the operation. Errors not recorded on spans via span.record_exception() and span.set_status(ERROR). Missing sampling configuration - either no sampling (100% in production is expensive) or aggressive sampling that drops error traces. Trace-log correlation gaps where log entries cannot be joined to their parent trace via trace_id and span_id fields. Missing spans at service boundaries: outbound HTTP calls, database queries, cache operations, queue publish/consume.

4. Metric naming conventions. Metric names that do not follow Prometheus (snake_case, unit suffix) or CloudWatch (PascalCase, namespace/dimension) conventions consistently. High-cardinality label values (user IDs, request paths with dynamic segments, full URLs) that will explode metric storage. Missing standard metrics: request rate, error rate, latency histograms (p50/p95/p99), saturation (queue depth, connection pool usage, thread pool utilization). Metrics that measure activity but not outcomes - counting invocations without tracking success/failure/duration. Inconsistent unit suffixes (_seconds vs _ms vs _duration vs no suffix).

5. CloudWatch alarm coverage. Services, Lambda functions, queues, or databases without alarms on their critical failure modes. Missing composite alarms that correlate related signals (e.g., high error rate AND high latency AND queue depth growing). Alarms with static thresholds on metrics that have natural variance - missing anomaly detection where appropriate. Alarm actions that notify but do not escalate - no PagerDuty/SNS/OpsGenie integration for CRITICAL alarms. Missing alarms on: 5xx error rate, Lambda throttles and errors, SQS dead-letter queue depth, DynamoDB throttled requests, RDS connection count and CPU, API Gateway 4xx/5xx rates.