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, and produce compensating updates in dotnet/extensions. See the 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, which also hosts mcp, openai, anthropic, aws-bedrock, and azure-ai-inference conventions. They were previously managed in the consolidated 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.

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:

The skill can optionally be applied in those repos with the following adaptations:

• Apply the convention analysis, classification framework (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).
• 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. 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:

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

Content truncated.