oodle-o11y-context

O11y Change Context — Manifest Spine

This skill defines one thing: the O11y Change Context manifest, a small structured block an authoring agent writes into a pull request description. It is the connective tissue of the observability loop — the left-side reviewer (oodle-o11y-review) enriches it, and the right-side triage (oodle-triage) reads it back when an alert fires. This skill carries no instrumentation how-to; it is a shared contract the other two skills reference.

Write the block only when it is warranted (see Relevance gate). Its value is that a change's observability intent survives from the moment it is authored to the moment it breaks in production.

The block

Put this fenced block in the PR description. Keep the ## O11y Change Context header and the field keys exactly as written — downstream agents locate and parse the block by this shape.

## O11y Change Context
type: perf, bugfix                 # bugfix | perf | feature | critical-path | refactor | infra
touches: checkout-svc, order-repo  # deploy/service units changed
telemetry:
  + span checkout.place_order {attr: tenant, order_id}   — trace slow orders per tenant
  ~ metric checkout_latency_seconds (histogram)          — widened buckets; guards SLO
  - metric checkout_legacy_timer                          — removed; duplicate of above
guarded-by: SLO checkout-p99, monitor HighCheckoutLatency  # existing alerts over touched code
watch: N+1 on order lookup under load; cache hit-rate regression
gaps: no per-item span in the loop — deferred (cardinality); triage can't attribute per-SKU

• telemetry lines start with + (added), ~ (changed), or - (removed), followed by the signal and a short purpose. A signal whose purpose cannot be stated probably should not exist.
• Omit a field only when it genuinely has no content (e.g. no gaps). Never rename a field.

Field reference

Field	Meaning	Filled by	Why it matters downstream
type	Nature of the change	Author	Sets scrutiny level for review and triage. critical-path earns the deepest review.
touches	Deploy/service units changed	Author	Triage matches a firing alert's service to recent changes here.
telemetry	Signals added / changed / removed, each with a purpose	Author (drafts), Review (verifies)	Enforces "every signal serves a purpose, no duplicates."
guarded-by	Existing alerts/SLOs covering the touched code	Review (resolved from backend)	Confirms the alert↔code link at triage; flags high-risk changes.
watch	Risk hypotheses to watch post-deploy	Author + Review	Triage reads this first — the leading hypotheses are pre-written.
gaps	Telemetry deliberately not added	Review	Tells triage what the data cannot answer, so it stops chasing it.

Lifecycle

1. Author drafts type, touches, telemetry, and watch when opening the PR.
2. Review enriches — oodle-o11y-review resolves guarded-by from the live backend, appends gaps, and may upgrade type to critical-path when touched code sits under a critical SLO.
3. Merge — the block lives on in the PR history.
4. Triage reads — on an alert, oodle-triage finds recent PRs touching the alerting service and reads their manifests: watch and type focus the investigation, guarded-by confirms the alert↔code link, and gaps explains missing evidence.

Relevance gate

Write the block when the change touches instrumented or service code, or when its type is perf, critical-path, or bugfix. Skip it for docs-only, config-cosmetic, or otherwise trivial changes — an empty ritual block is noise. The reviewer skill makes the final call on relevance; when in doubt, include a short block over none.

Carrier

In v1 the manifest lives only in the PR description, read back at triage time through the GitHub or Linear MCP — or, when no GitHub MCP is present, the gh CLI (gh pr list, gh pr view). A durable git commit trailer and a tracked in-repo manifest file are deliberately deferred — revisit only if triage frequently lacks a discoverable PR for a deployed commit.

Stability contract

The ## O11y Change Context header and the field keys (type, touches, telemetry, guarded-by, watch, gaps) are a parsing contract. Other skills and future automation match on them — do not rename or reorder-away fields. Adding a new optional field is safe; renaming an existing one is a breaking change.