update-otel-genai-conventions

# Update OTel GenAI Conventions Analyze OpenTelemetry GenAI semantic-conventions changes — PRs, changelog snapshots, date ranges, or releases — primarily from [`open-telemetry/semantic-conventions-genai`](https://github.com/open-telemetry/semantic-conventions-genai), and produce compensating updates in `dotnet/extensions`. See the [Migration Note](#migration-note) below for context, including where these conventions were previously managed. ## Migration Note The OpenTelemetry GenAI semantic conventions are maintained in a dedicated repo: [`open-telemetry/semantic-conventions-genai`](https://github.com/open-telemetry/semantic-conventions-genai), which also hosts `mcp`, `openai`, `anthropic`, `aws-bedrock`, and `azure-ai-inference` conventions. They were previously managed in the consolidated [`open-telemetry/semantic-conventions`](https://github.com/open-telemetry/semantic-conventions) repo under the `area:gen-ai` label. Implications for this skill: - **Primary input source** is `semantic-conventions-genai`. The consolidated `semantic-conventions` repo remains a **fallback** for catch-up audits, historical context, and any in-flight PR that started there previously. - **Every PR is in scope for consideration**, because `semantic-conventions-genai` is specific to GenAI conventions. (In the consolidated `semantic-conventions` repo the `area:gen-ai` label scoped this work, and it still applies there for catch-up.) The repo does use more granular `area:*` labels (for example `area:mcp`, `area:inference`, `area:tools`, `area:embeddings`), which can help triage but are not required for scoping. - **No releases yet** in `semantic-conventions-genai`. <!-- TODO: remove the "no releases yet" framing once semantic-conventions-genai ships its first release --> The repo manages its changelog with **Towncrier**: the `CHANGELOG.md` `Unreleased` section is intentionally empty (fragments are compiled into it only at release time), so the live "what's new" view is the set of news fragments under `changelog.d/`, each named `<upstream-PR>.<type>.md` (types include `enhancement`, `bugfix`, `breaking`, `clarification`). Pin a snapshot via commit SHA / ref for reproducible audits. - **Release tagging is not proven yet.** Until the repo ships real GenAI releases, treat GitHub Releases plus the release tag's dereferenced commit as the workflow baseline, but actively compare it with other durable signals (CHANGELOG release headers, schema URLs, and observed tag naming). Report confidence in the approach used, and surface a PR-body caution if another release signal becomes clearly more dependable than the workflow baseline. - **GenAI version is now independent** of core semconv: it tracks its own version line. The schema URL `https://opentelemetry.io/schemas/gen-ai/X.Y.Z` is intended to carry the gen-ai version, but is **not published yet** (the repo's `README.md` `## Schema URL` section is `TODO`). The repo's `versions.env` holds only the **core semconv dependency** (`SEMCONV_VERSION`, currently `v1.42.0`) and the Weaver toolchain version — it does **not** carry the GenAI convention version, so do not treat `SEMCONV_VERSION` as the GenAI version. Until a GenAI release or schema URL exists, there is no published GenAI version number; identify the update by its `changelog.d/` fragment snapshot, pinned to a commit SHA / ref / date. - **Spec URL `https://opentelemetry.io/docs/specs/semconv/gen-ai/` currently resolves to a "Moved" stub** that states the GenAI conventions have moved to `semantic-conventions-genai` and is no longer maintained; it no longer renders the spec content. The `<see href>` in dotnet/extensions source files still points at this URL, so leave it for now but revisit retargeting it once OpenTelemetry publishes a canonical URL for the conventions (the repo's `README.md` `## Schema URL` section is currently `TODO`). <!-- TODO: once open-telemetry/semantic-conventions-genai publishes its canonical spec/schema URL, retarget the OpenTelemetry* doc-comment `<see href>` from the /docs/specs/semconv/gen-ai/ stub to that URL. --> - **PR numbering** is not interchangeable across repos. Always disambiguate with `open-telemetry/semantic-conventions#NNN` or `open-telemetry/semantic-conventions-genai#NNN` when there is any risk of collision. - **Doc-comment wording** in dotnet/extensions source still reads "Semantic Conventions for Generative AI systems v1.XX". The next convention-update PR should migrate this to "GenAI Semantic Conventions vX.Y.Z" — see [references/file-inventory.md §Version References](references/file-inventory.md#version-references). When a referenced PR number doesn't resolve in `semantic-conventions-genai`, check the consolidated `semantic-conventions` repo before assuming the input is invalid. ## Cross-repo applicability This skill lives in `dotnet/extensions` and its file paths, build commands, and PR-description conventions are tuned for that repo. The `semantic-conventions-genai` repo also hosts provider-specific areas (`anthropic`, `aws-bedrock`) whose dotnet instrumentation lives in **other** SDK repositories that we contribute to: | Upstream area | Repository | Notes | |---|---|---| | `anthropic` | [`anthropics/anthropic-sdk-csharp`](https://github.com/anthropics/anthropic-sdk-csharp) | Anthropic's official .NET SDK. | | `aws-bedrock` | [`aws/aws-sdk-net`](https://github.com/aws/aws-sdk-net) | AWS Bedrock instrumentation lives in the `BedrockRuntime` service library (`AWSSDK.BedrockRuntime`) inside the AWS SDK monorepo. | The skill can optionally be applied in those repos with the following adaptations: - **Apply** the convention analysis, classification framework ([references/change-classification.md](references/change-classification.md)), audit-table shape, area routing, doc-comment wording target ("GenAI Semantic Conventions vX.Y.Z"), version-reference grep recipes, and PR-description shape ([references/pr-description.md](references/pr-description.md)). - **Do not assume** dotnet/extensions-specific paths (`src/Libraries/Microsoft.Extensions.AI*/`), the `OpenTelemetryConsts.cs` constants layout, the API-baseline workflow, or the build/test commands in [references/build-commands.md](references/build-commands.md). Use the target repo's own conventions for code structure, constants organization, and validation. - **Scope by repo**: when running in another repo, the in-scope upstream area is the one that repo instruments (e.g. `anthropic` in `anthropics/anthropic-sdk-csharp`, `aws-bedrock` in the `BedrockRuntime` library of `aws/aws-sdk-net`). Other areas are out of scope from that repo's perspective even though they remain in scope for `dotnet/extensions`. - **Pre-flight** still applies — search open PRs in the target repo for prior coverage before producing a plan. ## Mode Detection Determine the operating mode from the user's request: | Signal | Mode | |--------|------| | User asks to "audit" current implementation or "check alignment" with conventions | **Mode 1: Audit** | | User asks to "update for vX.Y" or "apply vX.Y changes" in autopilot / one-shot | **Mode 2: Autopilot** | | User asks to "generate a prompt" or "delegate to Copilot" or "CCA prompt" | **Mode 3: CCA Prompt** | | Running inside Copilot Coding Agent with a prompt referencing this skill | **Mode 4: CCA Implementation** | | User is in `/plan` mode, asks to "plan" changes, or asks to "implement" / "apply" changes | **Mode 5: Plan-then-Implement** | | User asks to `/review` or "review" convention changes | **Mode 6: Review** | If unclear, default to **Mode 5** (Plan-then-Implement) and offer Mode 3 as an alternative. ## Input Handling `semantic-conventions-genai` does not yet publish releases. Until it does, the user typically provides one of: - **PR references** in `semantic-conventions-genai` — full URL, `#NNN`, or `open-telemetry/semantic-conventions-genai#NNN` form. (No `area:` label filter is needed: the repo is gen-ai-focused by definition.) - **A `changelog.d/` snapshot** — a commit SHA, branch ref, or a `https://github.com/open-telemetry/semantic-conventions-genai/tree/{ref}/changelog.d` URL pinning the Towncrier news fragments at a point in time. (The `CHANGELOG.md` `Unreleased` section stays empty until release, so use the fragments — not `CHANGELOG.md` — for unreleased work.) - **A date range or "since last update"** — list of PRs merged to `semantic-conventions-genai`'s `main` between two refs / dates. - **A release version or release URL** — once releases exist (`https://github.com/open-telemetry/semantic-conventions-genai/releases/tag/{version}`). For **catch-up or historical work**, the consolidated `semantic-conventions` repo is still valid input: - A **semantic-conventions release version** (e.g. `v1.40.0`) → fetch from `https://github.com/open-telemetry/semantic-conventions/releases/tag/{version}` (filter to `area:gen-ai` PRs). - A **release URL** from `semantic-conventions` → fetch the release notes directly. - **PR references** from `semantic-conventions` — only the ones with `area:gen-ai`. Use the `open-telemetry/semantic-conventions#NNN` form to disambiguate from `semantic-conventions-genai` PR numbers. When PR numbers are given without a full URL, default to `semantic-conventions-genai` and fall back to the consolidated `semantic-conventions` repo only if the PR doesn't exist in `semantic-conventions-genai` or the user explicitly references it. ## Release Tagging Signal Analysis For every audit or implementation pass that creates or refreshes an upstream-scan tracking PR, include a concise release-tagging analysis. The current workflow baseline is: 1. Read GitHub's latest release for `open-telemetry/semantic-conventions-genai`. 2. Resolve that release's `tag_name` through `refs/tags`, dereferencing annotated tags to the commit they point at. 3. Treat the release as ready for a maintained PR only when that resolved commit equals the PR body's recorded `upstream-scan-ref`. Compare that baseline with all durable release signals available at the scanned ref: - GitHub Releases and the resolved release tag commit. - `CHANGELOG.md` release headers produced by Towncrier. - Published schema URLs such as `opentelemetry.io/schemas/gen-ai/X.Y.Z`, once they exist. - Stable tag naming patterns, if the repo begins publishing tags without GitHub Releases. Report confidence using these meanings: - `high`: the signal is published and tied to an exact commit or schema version that matches the audited GenAI conventions. - `medium`: the signal identifies a version, but the exact commit relationship is not proven. - `low`: the signal is inferred from non-release data such as fragments, core semconv dependency versions, or naming guesses. - `none`: no published GenAI release signal exists. If a different release signal becomes clearly dependable and conflicts with the workflow baseline, keep the workflow behavior unchanged for that run, but add the PR-description `> [!CAUTION]` block described in [references/pr-description.md](references/pr-description.md). The block must name the signal found and recommend the specific skill and/or workflow change needed. ### In-scope areas The `semantic-conventions-genai` repo hosts conventions for several areas, all of which this skill covers (with placement guidance in [references/implementation-patterns.md](references/implementation-patterns.md)): | Upstream area | Maps to in dotnet/extensions | |---|---| | `gen-ai`, `gen-ai/agent` | `Microsoft.Extensions.AI` core (e.g. `OpenTelemetryChatClient`) | | `mcp` | Currently no instrumentation; forward-looking — flag as a watch-list item if changes appear | | `openai` | `Microsoft.Extensions.AI.OpenAI` | | `anthropic` | Out of scope for `dotnet/extensions` today (no provider package). Implications land in [`anthropics/anthropic-sdk-csharp`](https://github.com/anthropics/anthropic-sdk-csharp) — apply this skill there per [Cross-repo applicability](#cross-repo-applicability). | | `aws-bedrock` | Out of scope for `dotnet/extensions` today (no provider package). Implications land in the `BedrockRuntime` service library of [`aws/aws-sdk-net`](https://github.com/aws/aws-sdk-net) — apply this skill there per [Cross-repo applicability](#cross-repo-applicability). | | `azure-ai-inference` | Corresponding provider package, if/when one exists in this repo; otherwise out of scope | When classifying a change, identify its area as follows. `gen-ai`, `mcp`, `openai`, and `aws-bedrock` each have a YAML registry under `model/<area>/`, so use that path. `anthropic` and `azure-ai-inference` do **not** have a `model/` registry today; they are documented only as provider pages under `docs/gen-ai/<provider>.md`. All human-readable docs live under `docs/gen-ai/` (for example `docs/gen-ai/openai.md`, `docs/gen-ai/mcp.md`, `docs/gen-ai/anthropic.md`), not under `docs/<area>/`. ### Existing dotnet/extensions PR Preflight For **Mode 1: Audit** and **Mode 5: Plan-then-Implement**, after resolving the requested input identifiers but before doing deeper analysis or creating a plan, search open pull requests in `dotnet/extensions` to determine whether another PR already appears to cover the requested update. Search using the requested release version, CHANGELOG ref, date range, or upstream PR numbers, plus relevant terms such as `gen-ai`, `GenAI`, `semantic conventions`, `semantic-conventions-genai`, `semconv-genai`, `OpenTelemetry`, `OTel`, and any in-scope area name (`MCP`, `OpenAI`, `Anthropic`, `Bedrock`, `Azure AI Inference`) that matches the changes you're working from. If one or more likely matching PRs are open, report the PR number, title, author, URL, and the signal that matched. Then stop and state that the audit or plan is not proceeding because an open PR already appears to cover the update. Do not silently ignore search failures. If GitHub search/listing is unavailable, report the problem and ask the user whether to proceed without the preflight. A standing **upstream-scan tracking PR** (one carrying the `# meai-otel-genai-worker:state:begin` block) is the exception: it is the durable scan record, not a blocking duplicate. When the preflight surfaces it, continue rather than stopping -- the maintaining workflow owns how that PR is created and incremented. ### Analyzing the Release / PRs 1. **Fetch the release notes** or PR descriptions and identify all gen-ai changes 2. **Read** [references/file-inventory.md](references/file-inventory.md) to understand which files in this repo are affected 3. **Classify each change** using [references/change-classification.md](references/change-classification.md) 4. **Check current state** — read the current source files to determine what is already implemented vs. what needs new work 5. **Build a changes audit table** showing each semantic convention change, its classification, and required action For Step 4, read the source files listed in [references/file-inventory.md](references/file-inventory.md) (`OpenTelemetryConsts.cs`, `OpenTelemetryChatClient.cs`, `OpenTelemetryEmbeddingGenerator.cs`, `Common/FunctionInvocationProcessor.cs`, and any other OpenTelemetry* files). ### PR Title and Description Guidance When creating or updating a PR after implementing GenAI semantic-conventions changes (from either repo), follow [references/pr-description.md](references/pr-description.md) for the title format and the changes-table shape. For a recurring **upstream-scan tracking PR** (the kind carrying the `# meai-otel-genai-worker:state:begin` block), that reference also defines the full body template -- the implemented-changes table, the merged and in-flight applicability tables, and, at the very bottom, the machine-readable tracking state block (the body ends there). --- ## Mode 1: Audit Audit the current gen-ai semantic conventions implementation against the latest published conventions to identify gaps, inconsistencies, or missed updates. Produces a plan that can be implemented locally (Mode 5) or delegated to CCA (Mode 3). 1. Complete the **Existing dotnet/extensions PR Preflight** above. If a matching open PR exists, report it and stop. 2. **Determine the current implemented version**: Read the version reference from `OpenTelemetryChatClient.cs` doc comment to identify which convention version the codebase claims to implement 3. **Check for version drift**: Verify every file with a gen-ai semantic conventions version reference uses the same version. Use the search command from [references/file-inventory.md](references/file-inventory.md#version-references). If files reference different versions, flag that as a critical gap requiring investigation.