# Measurable > Ensures every delivery ships with the telemetry needed to prove its impact and catch its own regressions: RUM/analytics events for user-facing web changes (delegates to rum-tracking), OpenTelemetry traces/metrics/structured logs for new or changed API endpoints, and explicit error/warning signal paths so failures surface instead of going silent. Modes: guide (default), implement, audit, setup. `setup` runs a first-time interview that records the project's telemetry stack, per-package instrumentation approach for monorepos, and regression-detection expectations as a committed Observability Profile. Triggers on "is this measurable", "add telemetry", "instrument this endpoint", "check observability coverage", "add RUM and API telemetry", "will we know if this regresses", "set up observability profile", "/measurable". - Skill: `mthines/measurable` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add mthines/measurable` - Raw SKILL.md: https://api.skillmd.com/api/skills/mthines/measurable/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - License: MIT - Author: mthines (https://skillmd.com/u/mthines) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mthines/measurable --- # Measurable Makes "we shipped it" and "we can see it" the same statement. A change is only done when its impact is measurable and its regressions are visible — this skill decides what telemetry a diff needs, writes or audits it, and records a per-repo profile so the answer doesn't have to be re-derived every time. > **This `SKILL.md` is a thin index.** Detailed rules live in `rules/*.md` > and load on demand. The profile template lives in `templates/*.md`. > > **Composes, does not duplicate.** Frontend event design is > [`rum-tracking`](../../analysis/rum-tracking/SKILL.md)'s job — this skill > only decides *whether* a user-facing change needs RUM and hands off to it. > Backend span/metric semantic conventions belong to the `otel-instrumentation` > and `otel-semantic-conventions` skills (from the > [dash0 agent-skills repo](https://github.com/dash0hq/agent-skills)) when > installed — invoked via `Skill()`, skipped silently otherwise, with > [`rules/backend-instrumentation.md`](./rules/backend-instrumentation.md) as > the built-in fallback. Persistence for the Observability Profile is > [`persistent-memory`](../../authoring/persistent-memory/SKILL.md)'s > `project-shared` tier — this skill never invents its own storage layer. --- ## Mode Detection Parse `$1` as the mode. State the detected mode in one line before continuing. | Mode | Default | Trigger | | ----------- | ------- | ------------------------------------------------------------------------- | | `guide` | **yes** | "is this measurable", "what telemetry do I need", default if no mode | | `implement` | | "add telemetry", "instrument this", "add RUM and API telemetry" | | `audit` | | "audit observability", "check observability coverage", "--diff", aw Phase 4 gate | | `setup` | | "set up observability profile", "first-time setup", "/measurable setup" | If `$1` is a diff, PR, file, or directory, treat it as the scope for `implement` or `audit`. --- ## Workflow by Mode ### Guide mode (default) The user is deciding *whether* and *what* telemetry a change needs. 1. Load [`rules/scope-detection.md`](./rules/scope-detection.md) and classify the change: frontend (web), frontend (mobile), backend/API, infra, or mixed. In a monorepo, check for a committed Observability Profile first (see [`rules/setup-profile.md`](./rules/setup-profile.md)) so package boundaries and stack choices don't have to be re-guessed. 2. For a frontend classification, recommend the user-facing events per [`rules/frontend-rum.md`](./rules/frontend-rum.md) (thin pointer into `rum-tracking`). 3. For a backend/API classification, recommend the spans, metrics, and structured logs per [`rules/backend-instrumentation.md`](./rules/backend-instrumentation.md). 4. Regardless of classification, name the specific regression signal — the metric, alert, or dashboard panel that would turn red if this change broke — per [`rules/regression-signals.md`](./rules/regression-signals.md). "We added a log line" is not a regression signal; "P99 latency on `POST /checkout` is now tracked and alerts at 2× baseline" is. 5. Do not prescribe code yet — that's `implement` mode. Guide mode ends with a short, concrete list: signals to add, and why each one is the one that would catch a regression. ### Implement mode The user (or the `autonomous-workflow` Phase 3 trigger) wants the instrumentation written. 1. Run the Guide-mode classification (Step 1 above) first — never write telemetry code without first stating what kind of change this is. 2. Frontend user-facing change → delegate: ``` Skill("rum-tracking", "implement", "") ``` This skill does not re-implement event design; it only confirms the delegation happened and that the resulting events map to a named regression signal (Step 4 above). 3. Backend/API change → follow [`rules/backend-instrumentation.md`](./rules/backend-instrumentation.md): a span per new/changed operation with OTel semantic-convention attributes, a RED metric (rate, errors, duration) if the operation is on a hot path, and a structured log at the point of failure. Prefer delegating to `Skill("otel-instrumentation")` / `Skill("otel-semantic-conventions")` when installed; the rule file is the fallback when they are not. 4. Either path → apply [`rules/regression-signals.md`](./rules/regression-signals.md) so errors and warnings are never silent: span status set on failure, a log at `error`/`warn` severity with enough context to triage without reproducing, and — when the Observability Profile names an existing dashboard or check rule for this package — a note that it now covers the new path (never auto-edit dashboards/alerts; that's `dash0`'s job in Dash0 chat, not this skill's). 5. Report what was added as a short "Observability" summary (one line per signal, with file:line) — `autonomous-workflow` Phase 6 folds this into the PR walkthrough. ### Audit mode The user (or the `autonomous-workflow` Phase 4 gate) wants an existing diff checked for coverage gaps, without writing anything. 1. Walk [`rules/audit-checklist.md`](./rules/audit-checklist.md) against the diff (or the target file/directory if no diff is given). 2. Classify each finding: `missing` (no signal at all for a changed path that needs one), `unlinked` (a signal exists but maps to no regression detector — Step 4 of Guide mode), or `pass`. 3. Cite a file path and line number for every finding. 4. Output a ranked list. **Advisory by default** — `missing` and `unlinked` findings are both reported, neither blocks. Pass `--strict` to make `missing` findings on `web`/`mobile`/`api`/`worker` paths block the caller's gate (`unlinked` stays advisory even in `--strict`, since not every signal needs a bespoke dashboard on day one). This mirrors how `critical` and `optimize-approach` ship non-blocking by default in this registry — a brand-new coverage heuristic earns a hard gate only once a team has opted in, not on day one. 5. Never auto-edit in `audit` mode — that is what `implement` mode is for. **Callers of `audit` mode.** `autonomous-workflow` Phase 4 (its Observability Gate) and the `pr-reviewer` agent's measurability lens (Step 2.4e, via `agents/shared/rules/measurability-review.md`) are both `audit`-only consumers. `autonomous-workflow` stays advisory unless a run opts into `--observability-strict`; the **reviewer defaults to strict** (a repo opts down with `measurable: advisory`), because a merged change that ships a new failure mode with no signal is the case the lens exists for. The reviewer additionally gates the call behind two conditions of its own — the diff must touch a `web`/`mobile`/`api`/`worker` path **and** add or alter observable behaviour — so a refactor PR never reaches this mode at all. Neither caller may invoke `implement`: one is a gate, the other is read-only. ### Setup mode First-time (or repo-onboarding) interview that records durable project facts so every later `guide`/`implement`/`audit` run stops re-deriving them. 1. Follow [`rules/setup-profile.md`](./rules/setup-profile.md) end to end: interview, monorepo package map, write via `persistent-memory` (`project-shared` tier), confirm. 2. Re-run any time the stack changes or a new package is added — `setup` is idempotent and updates the existing profile rather than duplicating it. --- ## Required Reading by Mode Load on demand — do not preload. | Mode | Files | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `guide` | [`rules/scope-detection.md`](./rules/scope-detection.md), [`rules/frontend-rum.md`](./rules/frontend-rum.md), [`rules/backend-instrumentation.md`](./rules/backend-instrumentation.md), [`rules/regression-signals.md`](./rules/regression-signals.md) | | `implement` | Same as `guide`, plus the delegated skill's own required reading (`rum-tracking`, `otel-instrumentation` when installed) | | `audit` | [`rules/audit-checklist.md`](./rules/audit-checklist.md), [`rules/scope-detection.md`](./rules/scope-detection.md) | | `setup` | [`rules/setup-profile.md`](./rules/setup-profile.md), [`templates/observability-profile.template.md`](./templates/observability-profile.template.md) | --- ## Core Principles 1. **A signal without a regression detector is not coverage.** Emitting a span or a log is necessary but not sufficient — name what would alert or what dashboard would show the break. Anti-pattern: "instrumented" meaning only "some code now calls a tracer." 2. **RUM and API telemetry are two different jobs, not one.** Frontend product-analytics event design stays owned by `rum-tracking`; this skill decides *whether* a change needs it and folds it into the same coverage picture as backend spans/metrics/logs. 3. **The Observability Profile is the source of truth for "how does this repo do telemetry."** Never re-guess the stack or the monorepo package map when a profile exists; run `setup` once, `guide`/`audit` read it after. 4. **Errors and warnings are first-class deliverables.** A change that adds a new failure mode without a way to see that failure mode in production is incomplete, regardless of test coverage. 5. **Advisory on frontend/backend code, hands-off on Dash0 config.** This skill writes application-level instrumentation. It never creates or edits dashboards, alerts, or SLOs directly — those are proposed through Dash0 chat (the `dash0` agent) so a human reviews and creates them there. 6. **Companions skip silently.** `rum-tracking`, `otel-instrumentation`, `otel-semantic-conventions`, and `persistent-memory` are all optional — degrade to the built-in rule files and say so in one line, never block. ## Anti-patterns (one-liners) - Calling a change "instrumented" because a log line was added, with no metric or alert that would ever surface a regression. - Re-deriving the monorepo package map or telemetry stack every run instead of running `setup` once and reading the profile. - Writing frontend analytics events inline instead of delegating to `rum-tracking`'s centralized wrapper. - Swallowing an error (`catch {}`) without a log at `error` severity and a span status flip. - Editing a Dash0 dashboard or check rule directly from this skill instead of proposing it through Dash0 chat. - Treating `audit` mode findings as blocking by default — they're advisory unless the caller explicitly passed `--strict`, and even then `unlinked` findings never block.