# Observability Designer

> Designs SLIs/SLOs, structured logs, traces, and alert quality for a feature or service. Use when shipping new paths or fixing noisy/missing alerts. Emits OBS_PLAN. Never recommends alert spam or metrics without a user/journey signal.

- Skill: `willianbs/observability-designer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add willianbs/observability-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/willianbs/observability-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: willianbs (https://skillmd.com/u/willianbs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/willianbs/observability-designer

---


# Purpose

Make the system operable: what to measure, log, trace, and alert on—with owners and noise control.

# When to Use / When NOT to Use

**Use when:** new services/features; after incidents; alert fatigue; missing dashboards; before deploy of HighRisk paths.

**Do not use when:** pure algorithm-local changes with no runtime surface; writing the full Grafana JSON unless asked.

# Preconditions

Feature/service scope and rough user journey. Prefer CONTEXT_PACK + SLOs if they exist.

# Inputs / Outputs

**Inputs:** scope, IMPACT_REPORT/INCIDENT_LOG optional, existing metrics/alerts if known.

**Outputs:** `OBS_PLAN`

# Upstream / Downstream

**Upstream:** delivery-planner, incident-commander, performance-auditor, engineering-os.

**Downstream:** feature-implementer, test-strategy-designer, quality-gate (deploy), postmortem-writer.

# Core Principles

1. SLIs from user journeys, not vanity counters.
2. Alerts need: signal, threshold, ownership, runbook link, severity.
3. Prefer fewer high-quality alerts over many noisy ones.
4. Structured logs with correlation IDs; no secrets/PII in log bodies.
5. Traces on boundaries (entry, datastore, external calls).
6. RED/USE as defaults; adapt to stack.
7. Every alert answers “what do I do at 3am?”.

# Process

1. Journeys / golden signals for the scope.
2. SLIs + SLO targets (or explicit “no SLO yet”).
3. Metrics list — name, type, labels (cardinality-safe).
4. Logging plan — events, fields, redaction.
5. Tracing plan — spans, attributes.
6. Alerts — condition, sev, routing, runbook outline; explicitly suppress noisy candidates.
7. Dashboard minimum viable views.
8. Decision.

# Evidence Requirements

Tie SLIs to real endpoints/jobs. Cite existing metric names when present.

# Stop Conditions / Failure Modes

| Condition | Action |
|-----------|--------|
| Alert with no action/runbook | Revise — do not ship that alert |
| High cardinality label proposal | Block that label |

# Severity + Confidence

Missing observability on SEV-1 path → High for deploy-gate conditions.

# Output Contract

```
## OBS_PLAN
Journeys/SLIs/SLOs: ...
Metrics: ...
Logs: ...
Traces: ...
Alerts: ...
Dashboards: ...
Decision: Proceed | ProceedWithConditions | Revise | Block
```

# Handoffs

**feature-implementer**, **quality-gate**, **incident-commander**, **performance-auditor**.

# Never

- Never log secrets or raw PII.
- Never page on symptoms without ownership.
- Never require 50 metrics for a tiny feature.