The /instrumenting-for-observability Skill

What it does

instrumenting-for-observability adds the signals you’ll need when this change breaks in production — designed from the failure questions backward, never from “interesting” code forward.

Once code is live, the only thing knowable about it is what it records. A failure that was never instrumented can’t be explained later; that debt can’t be paid after the incident window closes.

Instrumentation is designed backwards from the questions it must answer, never forwards from the code.

A question with no signal is a gap. A signal that answers no question gets deleted.

When to reach for it

• A new endpoint, job, consumer, or user-facing flow is about to merge
• An existing path is changing how it can fail
• You’re reviewing whether a diff could be debugged at 3am
• A retro found the outage was invisible
• Someone asks for “logging” or “metrics” without saying which questions they answer

Do not use for:

Situation	Better fit
Product analytics / funnels / adoption	Separate taxonomy and privacy posture
Dashboard, alert, or SLO configuration	Stops at signals those are built from
Retrofitting an entire service	Scope is one change
Diagnosing a live incident	Use existing telemetry; add gaps after
Learning an unfamiliar telemetry API	finder first
Temporary debug trail for one bug	debug-flow

Prerequisites

Assumes the codebase already has telemetry, metrics, or structured logging to match. With none present, the skill recommends signals and a setup rather than unilaterally introducing a vendor. Stack-agnostic by design.

How it works

1. Match the repo — Copy existing imports, naming, labels, and helpers. Don’t invent a parallel scheme.
2. Write failure questions first — Working at all? Broke? Slow? Everyone or a subset? Roll back? What happened to this case?
3. Map one signal per question — Counter, histogram, gauge, span, or log — with the graph-vs-investigate heuristic.
4. Apply hard rules — Bounded cardinality on metric labels; IDs and raw messages belong in logs/traces, not metric labels.
5. Implement in the repo’s style — Prefer local wrappers over raw SDK calls.
6. Prove the questions are answerable — Call out gaps in the PR description.

What you get

Targeted instrumentation for one change: the failure questions, the signals that answer them, and call sites that match existing conventions. Dashboard and alert wiring stay out of scope.

Cardinality rules and the RED starting set live in the source skill.

Common questions

Why not log everywhere interesting?
Volume tracks code complexity, not operational risk. Questions first give you a prune rule in both directions.

Can user IDs be metric labels?
No. High-cardinality labels explode time series. Put identifiers on structured logs or trace attributes.

What if there’s no telemetry in the repo yet?
Stop and recommend signals plus a library. Don’t sneak a vendor into a feature PR.

It’s working if

• Failure questions are written before any signal is chosen
• Each signal maps to a question; orphans are deleted
• Metric labels are small, enumerable sets
• New code matches existing naming and helpers
• You could answer the 3am questions from the signals alone

Where it fits

Ship-time twin of debug-flow: one is temporary evidence for a live bug; this one is permanent evidence for the next outage. Use finder when you need to learn the vendor API before writing call sites.