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](../oodle-o11y-review/SKILL.md)) enriches it, and the right-side triage ([oodle-triage](../oodle-triage/SKILL.md)) 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](#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

Lifecycle

1. Author drafts type, touches, telemetry, and watch when opening the PR.
2. Review enriches — [oodle-o11y-review](../oodle-o11y-review/SKILL.md)

resolves guarded-by from the live backend, appends gaps, and may upgrade type to critical-path when touched code sits under a critical SLO.

1. Merge — the block lives on in the PR history.
2. Triage reads — on an alert, [oodle-triage](../oodle-triage/SKILL.md) 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.