observability-verification

Observability verification

Use this skill at Stage 6c (observability gate) to verify that every metric, log, and trace the design-spec promised is actually emitted by the shipped code. The most common failure mode this catches: a design says "we'll emit a counter feature_x_changes_total" and the code never adds it.

When to use

• Stage 6c runs on full and hotfix tracks. Those are the tracks where the brief's §9 "Observability requirements" is mandatory.
• The platform role owns this stage; consult Backend/Frontend on what they actually added.

When to skip

This stage is not in nano, config-only, dep-update, quick tracks. If you're on one of those, this skill doesn't apply. If you're on full / hotfix and the brief genuinely has no observability requirements (rare), set every required array to [] and PASS the gate.

Procedure

1. Extract the required signals

Read pipeline/brief.md §9 "Observability requirements" and pipeline/design-spec.md for any expansion. Categorize each requirement:

• Metrics: counters / gauges / histograms with specific names. Look for prose like "counter X with labels Y, Z" or explicit metric-name lists.
• Logs: log statements with specific event types. Either named events (e.g. "log every opt-in change at INFO") or substring-matchable phrases.
• Traces: span names. Many briefs don't require traces explicitly — check the design-spec for §Tracing or §Distributed-tracing sections.

Make three lists. Empty is fine for any category the brief doesn't require.

2. Verify each signal in the code

For each required signal, find concrete evidence in the shipped code:

Metrics — typical patterns to grep for:

• Prometheus / OpenTelemetry: counter.add(...), Counter("name", ...), prometheus_client.Counter("name"), metrics.counter("name")
• StatsD: statsd.increment("name.path"), dogstatsd.gauge
• Build a regex: grep -rE "name|MetricName.replace(/_/g, '[._]')" — many libs normalize separators