Problem

ARM deployment errors are the largest error category at 45.26% of all errors (~57,956). While azd correctly parses the nested ARM error tree and displays all error lines, the actual root cause (the deepest/most-specific error code) is not distinguished from wrapper errors. Users see multiple error lines and must manually identify which one is the real problem.

Current Behavior

azure_deployment_error.go (lines 87-149) recursively parses ARM error details and suppresses generic wrappers (DeploymentFailed, ResourceDeploymentFailure). The Error() method (lines 53-69) flattens the tree into a list of messages displayed to the user. All error lines appear with equal visual weight.

Proposed Solution

1. Add a RootCause() *DeploymentErrorLine method to AzureDeploymentError that returns the deepest/leaf error code in the error tree
2. In user-facing output, visually distinguish the root cause line (e.g., prefix with Root cause: or use distinct formatting)
3. Add a lookup table mapping the top-10 most common ARM root cause codes to actionable user guidance:
   • InsufficientQuota / SkuNotAvailable: Suggest checking quota with az vm list-usage or changing region
   • AuthorizationFailed: Suggest checking RBAC role assignments
   • InvalidTemplate / ValidationError: Suggest running az deployment group validate
   • ResourceNotFound: Suggest checking resource dependencies and deployment ordering
   • Conflict / FlagMustBeSetForRestore: Suggest purging soft-deleted resources
4. Include the root cause code in the telemetry error classification for better signal

Data Reference

Source: AzdProvisionErrorsByTemplate + AzdDeploymentErrorsByTemplate (DevCli on ddazureclients)

• Total ARM errors: 57,956 (45.26%)
• Top root causes: Template/Validation (7.27%), Quota/Capacity (2.82%), Authorization (2.68%), Resource Conflict (2.53%)