Skip to content

oliverv/caro / .agents/skills/oma-observability

oma-observability

Unverified

Design or troubleshoot telemetry, SLOs, and incident diagnostics. Route to the relevant signal, system boundary, or vendor guide.

FileKindSize
SKILL.mdskill md14.6 KB
resources/anti-patterns.mdmarkdown45.7 KB
resources/boundaries/cross-application.mdmarkdown19.5 KB
resources/boundaries/multi-tenant.mdmarkdown17.9 KB
resources/boundaries/release.mdmarkdown12.4 KB
resources/boundaries/slo.mdmarkdown6.5 KB
resources/checklist.mdmarkdown15.0 KB
resources/examples.mdmarkdown15.7 KB
resources/execution-protocol.mdmarkdown9.5 KB
resources/incident-forensics.mdmarkdown23.3 KB
resources/intent-rules.mdmarkdown11.8 KB
resources/layers/L3-network.mdmarkdown17.6 KB
resources/layers/L4-transport.mdmarkdown14.6 KB
resources/layers/L7-application/crash-analytics.mdmarkdown17.6 KB
resources/layers/L7-application/mobile-rum.mdmarkdown15.8 KB
resources/layers/L7-application/waf.mdmarkdown16.6 KB
resources/layers/L7-application/web-rum.mdmarkdown17.3 KB
resources/layers/mesh.mdmarkdown20.0 KB
resources/matrix.mdmarkdown21.1 KB
resources/meta-observability.mdmarkdown23.5 KB
resources/observability-as-code.mdmarkdown21.8 KB
resources/signals/audit.mdmarkdown13.9 KB
resources/signals/cost.mdmarkdown17.2 KB
resources/signals/logs.mdmarkdown10.2 KB
resources/signals/metrics.mdmarkdown19.6 KB
resources/signals/privacy.mdmarkdown17.5 KB
resources/signals/profiles.mdmarkdown15.2 KB
resources/signals/traces.mdmarkdown19.1 KB
resources/standards.mdmarkdown12.7 KB
resources/transport/collector-topology.mdmarkdown11.9 KB
resources/transport/otlp-grpc-vs-http.mdmarkdown7.6 KB
resources/transport/sampling-recipes.mdmarkdown11.0 KB
resources/transport/udp-statsd-mtu.mdmarkdown6.3 KB
resources/vendor-categories.mdmarkdown17.7 KB

resources/intent-rules.md

View on GitHub
---
otel_spec: "1.x (stable API/SDK)"
otel_semconv: "1.43.0 (2026-07)"
---

# Intent Classification Rules

## Purpose

- Classify a user query into one of 7 intents to route to the right resources
- Used by Step 1 of `execution-protocol.md`
- This file is an **English-only intent classification reference**. Multi-language keyword detection (Korean, Japanese, Chinese, etc.) is owned by `.agents/hooks/core/triggers.json §oma-observability.keywords`; do not duplicate per-locale tokens here.

## Classification Priority

1. **Override flags**: always win, skip classification entirely (e.g., `--investigate`, `--tune`)
2. **Keyword pattern matching**: scan query for intent-specific keywords
3. **Signal detection**: contextual clues (tool names, error messages, metric names, cloud regions)
4. **Fallback**: `investigate + tune` parallel when no clear signal

## Override Flags

| Flag | Forced Intent |
|------|--------------|
| `--setup` | `setup` |
| `--migrate` | `migrate` |
| `--investigate` | `investigate` |
| `--alert` | `alert` |
| `--trace` | `trace` |
| `--tune` | `tune` |
| `--route` | `route` |

---

## The 7 Intents

### Intent 1: `setup`

Bootstrap a new observability pipeline or instrument a new service from scratch.
Use when the user is starting fresh: no existing pipeline, first-time SDK integration, or onboarding a new environment.

#### Keywords

| Category | Tokens |
|----------|--------|
| Primary | setup, install, bootstrap, instrument, configure, onboard, initialize, start, enable, add, integrate, begin, getting started, first time |
| Synonyms | init, SDK setup, OTel setup, collector setup, agent install |

**Signals:**
- "How do I add OTel to ..." queries
- Service name + "for the first time"
- New environment or cluster name mentioned with no existing config

#### Example Queries

- "Set up OTel stack on our k8s cluster"
- "Instrument our Node.js backend with OTel"
- "How do I enable tracing on a new Spring Boot service?"

#### Primary Route

`resources/vendor-categories.md` → category selection; `resources/transport/collector-topology.md` for Kubernetes

#### Secondary Considerations

`resources/standards.md` for semconv requirements before first instrumentation commit

---

### Intent 2: `migrate`

Move from a legacy tool to a modern equivalent. Applies to logging agents, APM platforms, and deprecated CNCF projects.

#### Keywords

| Category | Tokens |
|----------|--------|
| Primary | migrate, migration, transition, move, replace, upgrade, modernize, switch, deprecate, port, convert, off-board, phase out |
| Synonyms | Fluentd → Fluent Bit, legacy APM → OTel, lift-and-shift, rip-and-replace |

**Signals:**
- Source tool name (Fluentd, New Relic, Datadog, old APM) + destination intent
- "Replace", "away from", "moving off of"
- CNCF deprecation context (Fluentd 2025-10)

#### Example Queries

- "Migrating Fluentd to Fluent Bit per CNCF guidance"
- "Move from New Relic to OpenTelemetry"
- "How do I port StatsD metrics to OTLP?"

#### Primary Route

`resources/vendor-categories.md §(h) Log Pipeline` (deprecation notes); CNCF 2025-10 Fluentd migration guide

#### Secondary Considerations

`resources/transport/otlp-grpc-vs-http.md` for destination protocol selection during migration

---

### Intent 3: `investigate`

Production incident or bug root-cause analysis. Use when something is broken, degraded, or unexpectedly slow right now.

#### Keywords

| Category | Tokens |
|----------|--------|
| Primary | investigate, debug, diagnose, incident, outage, postmortem, forensics, root-cause, why, broken, failing, spike, degraded, 5xx, 403 storm, error rate, latency, slow, down, regression, N+1, slow query, connection pool, pool exhaustion, db span, memory leak, OOM, flame graph, stuck, WAF block, WAF false positive, firewall block, ruleset rollback, cascading failure, dependency outage, third-party outage, fail-closed, status page |
| Synonyms | RCA, postmortem, blameless review, p99 spike, tail latency, DB timeout, FP storm, edge 403, ruleset bump, third-party down |

**Signals:**
- HTTP status codes (5xx, 4xx) or error rate numbers
- Cloud region name mentioned with a problem symptom
- Service name + "suddenly", "again", "just started"
- Time window phrase ("since 14:00", "after deploy")

#### Example Queries

- "5xx spike in ap-northeast-2, need to find root cause"
- "Why is checkout service p99 high?"
- "Auth service started timing out after today's release; help"
- "Customers report 403s but our backend looks fine; check the WAF"
- "Stripe webhooks failing in bursts — is it us or a third-party outage?"

#### Primary Route

`resources/incident-forensics.md` (MRA + 6-dimension localization flow)

#### Secondary Considerations

`resources/signals/traces.md`, `resources/signals/logs.md`, `resources/boundaries/multi-tenant.md` (if single-tenant degradation pattern), `resources/layers/L7-application/waf.md` (if edge 403 storm / WAF FP suspected), `resources/boundaries/cross-application.md` (if third-party dependency outage suspected)

---

### Intent 4: `alert`

Define alerts, SLO burn-rate rules, or monitor configuration. Use when the user wants to be notified proactively before or during an incident.

#### Keywords

| Category | Tokens |
|----------|--------|
| Primary | alert, alarm, notification, burn-rate, SLO, SLI, SLA, threshold, page, warn, monitor, PrometheusRule, alerting rule, error budget, firing |
| Synonyms | burn rate alert, fast burn, slow burn, PD (PagerDuty), firing rule, recording rule |

**Signals:**
- SLO/SLI/SLA acronyms
- "Alert when ...", "notify me if ..."
- PrometheusRule, Alertmanager, or burn-rate framing
- Error budget percentage mentioned

#### Example Queries

- "Set up SLO burn-rate alert for payment service"
- "Need alerts when error budget is burning fast"
- "How do I configure a slow-burn SLO alert in Grafana?"

#### Primary Route

`resources/boundaries/slo.md`; `resources/observability-as-code.md` (PrometheusRule CRD, OpenSLO YAML)

#### Secondary Considerations

`resources/meta-observability.md §Section F` for meta-observability pipeline health alerts

---

### Intent 5: `trace`

Design or debug distributed tracing: propagators, baggage, cross-service context, or mesh trace continuity.

#### Keywords

| Category | Tokens |
|----------|--------|
| Primary | trace, tracing, propagator, traceparent, tracestate, baggage, span, distributed, context propagation, correlation, W3C, X-Amzn-Trace-Id, context break, missing spans |
| Synonyms | W3C Trace Context, B3, Zipkin, X-Ray trace, OpenTelemetry tracing, end-to-end trace |

**Signals:**
- "Trace breaks", "missing parent span", "trace not showing"
- Propagator format names (W3C, B3, X-Ray, Jaeger)
- Mesh or gateway name + trace context question
- Baggage field name mentioned

#### Example Queries

- "Our traces break at the Istio ingress; how to propagate context?"
- "Design baggage for multi-tenant trace correlation"
- "How do I bridge AWS X-Ray trace headers into W3C Trace Context?"

#### Primary Route

`resources/boundaries/cross-application.md` (propagator matrix); `resources/layers/mesh.md` (zero-code auto-instrumentation)

#### Secondary Considerations

`resources/signals/privacy.md` (baggage PII rules; no user identifiers in traceparent/baggage without redaction)

---

### Intent 6: `tune`

Optimize performance, reduce cost, tame cardinality, configure sampling, or fix throughput bottlenecks in the telemetry pipeline.

#### Keywords

| Category | Tokens |
|----------|--------|
| Primary | tune, optimize, performance, throughput, cost, cardinality, sampling, budget, reduce, bandwidth, MTU, rate-limit, too much, expensive, overhead, head sampling, tail sampling, drop |
| Synonyms | high cardinality, metric explosion, bill shock, DPM (data points per minute), ingest cost, backpressure |

**Signals:**
- Cost number with "jumped", "tripled", "too high"
- Cardinality, label explosion, or DPM framing
- UDP MTU or OTLP throughput question
- Sampling ratio or rate-limit configuration

#### Example Queries

- "Datadog bill jumped 3x: need to reduce cardinality"
- "UDP statsd throughput is low at peak"
- "How do I set a cost-aware tail sampling policy for the checkout service?"

#### Primary Route

`resources/transport/` (all 4 files: `udp-statsd-mtu.md`, `otlp-grpc-vs-http.md`, `collector-topology.md`, `sampling-recipes.md`); `resources/meta-observability.md §Cardinality`

#### Secondary Considerations

`resources/vendor-categories.md` for alternative tool selection when current vendor is causing the cost spike

---

### Intent 7: `route`

Multi-tenant, multi-cloud, or multi-region telemetry routing, isolation, data residency, or federation.

#### Keywords

| Category | Tokens |
|----------|--------|
| Primary | route, routing, multi-tenant, multi-cloud, region, residency, isolation, segregation, gateway, fan-out, federation, data locality, GDPR residency, pipeline split, tenant routing |
| Synonyms | data sovereignty, geo-fencing, per-tenant collector, routing_connector, OTel Collector routing |

**Signals:**
- Specific cloud region name + compliance or residency requirement
- "Tenant A vs Tenant B" pipeline separation
- Multiple collectors or clusters mentioned with routing context
- GDPR, PIPA, or data sovereignty regulation cited

#### Example Queries

- "Route tenant A telemetry to ap-northeast-2 only (GDPR residency)"
- "Federated collectors across 3 k8s clusters"
- "How do I fan-out logs to two different Loki stacks by tenant tier?"

#### Primary Route

`resources/boundaries/multi-tenant.md`; `resources/transport/collector-topology.md`

#### Secondary Considerations

`resources/boundaries/cross-application.md` for trust boundary enforcement when routing crosses application domains

---

## Ambiguous / Fallback

When no intent is detected with confidence:

- Default to `investigate + tune` in parallel (observability work is often both diagnosing a problem and reducing noise)
- Present both result sets; let the user pick
- If automation is critical (e.g., CI pipeline), require the user to pass an explicit flag

**Ambiguity resolution examples:**

| Query | Detected Intent | Reason |
|-------|----------------|--------|
| "OTel Collector configuration" | `setup` (or `tune` if already deployed) | "configure" matches setup; check for existing deployment context |
| "p99 high, why?" | `investigate` | Problem symptom + causal question |
| "How do I sample?" | `tune` | Sampling = throughput/cost optimization |
| "Tenant data isolation" | `route` | Isolation + tenant framing |
| "SLO alert setup" | `alert` | SLO + alarm keywords |
| "Want to drop Fluentd" | `migrate` | Deprecation + replacement intent |
| "Istio trace propagation" | `trace` | Mesh + trace context propagation |
| "Something off with OTel" (no detail) | `investigate + tune` fallback | No specific signal; dispatch parallel |

---

## Matching Algorithm

1. Lower-case both query and keyword list
2. For each intent, count keyword hits (whole-word boundary match)
3. Pick the intent with the highest score
4. On a tie, apply tiebreak priority: `investigate` > `setup` > `tune` > `alert` > `trace` > `route` > `migrate` (ordered by business-incident impact)
5. If all scores are zero: fall back to `investigate + tune` parallel with a clarification prompt

---

## Integration with Hooks

- **Multi-language keyword detection** at `UserPromptSubmit` is owned by `.agents/hooks/core/triggers.json §oma-observability.keywords` (entries for `*`, `en`, `ko`, `ja`, `zh`). That file is the single source of truth for activation tokens.
- This file documents the **English intent classification rules** consumed by `resources/execution-protocol.md §Step 1` once the skill has been activated.
- Override flags (`--investigate`, etc.) bypass keyword scoring entirely and force the named intent.
- When adding tokens for a new domain (e.g., WAF, cascading failure), update both: (a) English tokens in the relevant intent's Keywords table here, and (b) per-locale activation tokens in `triggers.json`.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall