oodle-o11y-context

O11y Change Context — Manifest Spine

このスキルが定義するのは、1つのものだけです。O11y Change Context マニフェスト、つまり作成エージェントがプルリクエストの説明に記述する、小さな構造化ブロックです。これは可観測性のループをつなぐ要です。左側のレビュアー（oodle-o11y-review）が内容を補い、右側のトリアージ（oodle-triage）がアラート発生時に内容を読み取ります。このスキルには計装方法の説明はなく、ほかの2つのスキルが参照する共通の契約です。

このブロックは、必要な場合にのみ記述してください（関連性の判定を参照）。変更の可観測性に関する意図を、作成時から本番環境で問題が発生する時まで保てることが、このブロックの価値です。

ブロック

このフェンス付きブロックをPRの説明に記述します。後続のエージェントはこの形式を使ってブロックを特定し、解析するため、## O11y Change Context ヘッダーとフィールドキーは記載どおりにしてください。

## 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 の各行は、+（追加）、~（変更）、-（削除）で始まり、その後にシグナルと簡潔な目的を記述します。目的を説明できないシグナルは、おそらく存在すべきではありません。
• フィールドを省略できるのは、実際に内容がない場合だけです（例：gaps がない場合）。フィールド名は変更しないでください。

フィールドリファレンス

フィールド	意味	記入者	後続処理で重要な理由
type	変更の性質	作成者	レビューとトリアージの精査レベルを設定します。critical-path は最も詳細なレビューの対象となります。
touches	変更されたデプロイ／サービス単位	作成者	トリアージでは、発火したアラートのサービスと、ここに記載された最近の変更を照合します。
telemetry	目的を添えた、追加／変更／削除されたシグナル	作成者（下書き）、レビュー（検証）	「すべてのシグナルに目的があり、重複がない」ことを徹底します。
guarded-by	変更箇所を対象とする既存のアラート／SLO	レビュー（ライブバックエンドから解決）	トリアージ時にアラート↔コードの関連を確認し、リスクの高い変更にフラグを付けます。
watch	デプロイ後に監視するリスク仮説	作成者 + レビュー	トリアージでは最初にここを読み、主な仮説を事前に把握します。
gaps	意図的に追加しなかったテレメトリ	レビュー	データでは何が分からないのかをトリアージに伝え、解明できない点の調査を打ち切れるようにします。

ライフサイクル

1. PRを作成する際に、作成者が type、touches、telemetry、watch の下書きを作成します。
2. レビューで内容を補います。oodle-o11y-review がライブバックエンドから guarded-by を解決し、gaps を追加します。また、変更箇所が重要なSLOの対象である場合、type を critical-path に引き上げることがあります。
3. マージ — ブロックはPRの履歴に残ります。
4. トリアージで読み取ります — アラート発生時に、oodle-triage がアラート対象のサービスに触れる最近のPRを見つけ、そのマニフェストを読み取ります。watch と type が調査の焦点を定め、guarded-by がアラート↔コードの関連を確認し、gaps が証拠の不足を説明します。

関連性の判定

変更が計装されたコードまたはサービスコードに触れる場合、あるいは type が perf、critical-path、bugfix のいずれかである場合に、ブロックを記述してください。ドキュメントのみの変更、設定の見た目だけの変更、その他の些細な変更では省略してください。内容のない形式的なブロックはノイズになります。関連性の最終判断はレビュアースキルが行います。迷った場合は、ブロックなしより短いブロックを記述してください。

格納場所

v1では、マニフェストはPRの説明にのみ格納し、トリアージ時にGitHubまたはLinear MCPを通じて読み取ります。GitHub MCPがない場合は gh CLI（gh pr list、gh pr view）を使用します。永続的なgitコミットトレーラーと、リポジトリ内で追跡するマニフェストファイルは意図的に後回しにしています。デプロイ済みコミットに対応するPRが見つからないことがトリアージで頻繁に起きる場合にのみ、再検討してください。

安定性の契約

## O11y Change Context ヘッダーとフィールドキー（type、touches、telemetry、guarded-by、watch、gaps）は、解析に関する契約です。ほかのスキルや将来の自動化処理がこれらを基準に照合するため、名前を変更したり、フィールドの順序を変えて並びを崩したりしないでください。新しい任意フィールドの追加は安全ですが、既存フィールドの名前変更は互換性を破壊します。