Extend azsdk_typespec_generate_authoring_plan with SDK breaking change detection

[samvaity]

Goal

When a dev writes TypeSpec, detect SDK breaking changes and include client.tsp mitigations in the authoring plan — before merge.

Today: Write TypeSpec → merge → pipeline fails → weeks of back-and-forth → fix client.tsp → repeat
Target: Write TypeSpec → authoring plan warns with SDK impact → dev fixes in same session → merge clean

Background

• azsdk_customized_code_update against Storage breaking changes got 90% right (Issue Detect and Resolve mgmt. SDK Breaking Changes Early in the Spec Authoring Stage #14675), confirming the patterns are well understood
• azsdk_typespec_generate_authoring_plan already knows all custom decorators and their applicable scenarios, but has limitations with complex cases (e.g., enum split into several enums)
• Crystal's testing showed that feeding SDK changelog into the tool enables accurate detection

Work Plan

Task 1: Build breaking change pattern database

Where: eng/common/knowledge/sdk-breaking-patterns.md (shared, reusable)

Document known breaking change patterns with:

• Detection rules (TypeSpec diff patterns and/or SDK changelog patterns)
• Per-language impact — the same TypeSpec change affects Java/.NET/Python/Go differently based on each language's breaking change policy and handling mechanisms
• Language-scoped mitigations using decorators with appropriate language scope
• Complexity level : simple patterns first (model rename) vs complex patterns (enum split into multiple enums with subset members)

Known gap/ limitations : Complex enum split scenario — tools know the right decorators but don't generate accurate sample code when an enum is split into several enums. Need concrete examples.

Task 2: Extend azsdk_typespec_generate_authoring_plan with SDK impact warnings

Where: azure-sdk-tools/tools/azsdk-cli/

• After generating the authoring plan, match planned changes against pattern database
• Include SDK IMPACT warnings in plan output with language-specific impact and scoped client.tsp fix code
• Accept SDK changelog as additional input for deeper detection
• For non-breaking changes, return plan as-is (zero overhead)

Task 3: Update azure-typespec-author skill to surface warnings

Where: azure-rest-api-specs/.github/skills/azure-typespec-author/

• Update SKILL.md workflow to include review of SDK impact warnings after Step 3 (plan retrieval)
• If warnings present, prompt user to accept and apply mitigations, or revise approach

Task 4: Validate with Storage scenario end-to-end

Use Crystal's Storage simulation (reverted PR #41684) as the test case:

• Feed Storage Java SDK changelog into azsdk_typespec_generate_authoring_plan
• Verify detection of all breaking change categories
• Verify correct language-scoped client.tsp mitigations, especially the enum split case
• Target: 90%+ accuracy

Related

• Issue Detect and Resolve mgmt. SDK Breaking Changes Early in the Spec Authoring Stage #14675 — Detect and Resolve mgmt. SDK Breaking Changes Early
• PR Add customization workflow to generate-sdk-locally skill #14821 — Added customization workflow to generate-sdk-locally skill
• PR #41684 — Storage client.tsp fix (human reference for enum split case)
• PR #42089 — Crystal's agent session that triggered the skill successfully