Perform an Azure Well-Architected Framework review of the current workload IaC and architecture, generating findings and GitHub issues for improvements.
This workflow performs a structured Azure Well-Architected Framework (WAF) review against your workload's IaC files and deployed infrastructure. It identifies risks across all 5 WAF pillars and creates GitHub issues to track remediation.
Prerequisites
Azure CLI (az) configured and authenticated
IaC files present in the repository (Bicep, Terraform, or ARM templates)
Service guides for the Azure services in use (https://learn.microsoft.com/en-us/azure/well-architected/service-guides/)
Workload-specific guidance relevant to the workload type (SaaS, mission-critical, AI, etc.)
If the microsoft.docs.mcp MCP server is available, use it to query the latest pillar checklists and service-specific recommendations.
Step 2: Discover IaC & Architecture
Establish the review scope, then inventory both the code and the live environment:
Confirm the Azure scope: Ask the user which subscription(s)/resource group(s) are in scope, or infer them from IaC parameters and confirm.
Scan the repository for IaC files:
Bicep: **/*.bicep, bicepconfig.json
Terraform: **/*.tf (azurerm/azapi providers)
ARM templates: **/azuredeploy*.json, **/*.template.json, files with $schema containing deploymentTemplate
Inventory live resources (always, even when IaC exists): az resource list --resource-group <rg> --output json (or subscription-wide), plus targeted az <service> show calls for configuration details the pillar checks need.
Compare IaC with live inventory: Flag drift — resources present in Azure but absent from IaC (portal-created), resources defined in IaC but not deployed, and configuration mismatches. Record drift findings for Step 3 (they typically map to the Operational Excellence pillar).
Identify key Azure services in use (compute, data, networking, security, observability) and generate a Mermaid architecture diagram.
Step 3: Pillar-by-Pillar Review
Pillar 1: Reliability
Availability zones enabled for zonal services (VMs, VMSS, AKS node pools, App Service, SQL, Storage ZRS)
Production SKUs support the required SLA (no Basic/Free tiers on critical paths)
Azure SQL / Cosmos DB backup and point-in-time restore configured with appropriate retention
Geo-redundancy configured where RPO requires it (GRS/RA-GRS storage, SQL failover groups, Cosmos DB multi-region)
Autoscale rules configured for App Service plans, VMSS, AKS (no fixed single instance for production)
Health probes configured on Load Balancer / Application Gateway / Front Door backends
Dead-lettering enabled for Service Bus queues/subscriptions and Event Grid subscriptions
Retry policies with exponential backoff implemented for transient fault handling
Disaster recovery plan defined (documented RTO/RPO, tested failover)
Pillar 2: Security
Managed identities used instead of service principals with secrets or connection strings
No hardcoded credentials, keys, or connection strings in IaC or code
Secrets stored in Azure Key Vault with RBAC authorization (not access policies)
Storage accounts deny public blob access and disallow shared key access where possible
Private endpoints (or at minimum service endpoints + firewall rules) for PaaS data services
NSGs restrict inbound traffic to minimum required ports/CIDRs (no * → * allow rules)
TLS 1.2+ enforced on all endpoints (minimumTlsVersion, httpsOnly)
Azure RBAC follows least privilege (no Owner/Contributor at subscription scope for workload identities)
Microsoft Defender for Cloud enabled on relevant resource types (az security pricing list)
Azure WAF (Application Gateway or Front Door) configured for public-facing web endpoints
Diagnostic settings send security logs to Log Analytics / Microsoft Sentinel
Pillar 3: Cost Optimization
Reservations or savings plans evaluated for steady-state compute (VMs, App Service, SQL)
Storage lifecycle management policies move blobs to cool/archive tiers
Right-sized SKUs based on actual utilization (no oversized VMs/App Service plans)
Dev/test environments use auto-shutdown schedules and Dev/Test pricing where eligible
Azure Budgets and cost alerts configured (az consumption budget list)
Unattached managed disks and orphaned public IPs identified and removed
Consumption/serverless tiers used for spiky or low-volume workloads (Functions, Container Apps, SQL serverless)
Log Analytics retention and data-cap settings tuned to avoid ingestion overruns
Pillar 4: Operational Excellence
All infrastructure defined as IaC (no manual portal changes; deny assignments or policy where feasible)
Consistent tagging strategy applied across all resources (owner, environment, cost center)
Azure Monitor alerts defined for key metrics and service health
Right-sized compute SKUs validated against load requirements
Caching implemented where beneficial (Azure Cache for Redis, CDN/Front Door caching)
Azure Front Door or CDN used for global static content delivery
Autoscale based on load metrics rather than fixed instance counts
Database performance tier appropriate (DTU vs vCore, elastic pools, Cosmos DB RU autoscale)
Premium/zone-redundant storage used for latency-sensitive disk workloads
Connection pooling and async patterns used for database and HTTP clients
Step 4: Risk Classification
For each finding, classify:
High Risk: Security vulnerability, single point of failure, no backup/recovery
Medium Risk: Suboptimal reliability, cost inefficiency, performance concern
Low Risk: Best practice deviation, minor optimization opportunity
Step 5: User Confirmation
🏗️ Azure Well-Architected Review Summary
📊 Review Results:
• IaC Files Analyzed: X
• Azure Services Identified: Y
• Total Findings: Z
• High Risk: A (immediate action required)
• Medium Risk: B (should address soon)
• Low Risk: C (nice to have)
🔴 Top High Risk Findings:
1. [Pillar]: [Finding] — [Why it matters]
2. [Pillar]: [Finding] — [Why it matters]
💡 This will create Z individual GitHub issues + 1 EPIC issue.
❓ Proceed with creating GitHub issues? (y/n)
Gate: Only proceed to Steps 6–7 if the user gives an explicit affirmative response (e.g. "y", "yes"). On a negative, ambiguous, or missing response, do not create any GitHub issues — output the full findings as formatted markdown to the console and stop.
Step 6: Create Individual Finding Issues
Label with "well-architected" and the pillar name (e.g., "security", "reliability").
Use this skill when the user explicitly asks to map, document, or onboard into an existing codebase. Trigger for prompts like "map this codebase", "document this architecture", "onboard me to this repo", or "create codebase docs". Do not trigger for routine feature implementation, bug fixes, or narrow code edits unless the user asks for repository-level discovery.
Run the AgentRC readiness assessment on the current repository and produce a static HTML dashboard at reports/index.html. Wraps `npx github:microsoft/agentrc readiness` and hands off rendering to the @ai-readiness-reporter custom agent. Supports policies (--policy) for org-specific scoring. Use when asked to assess, audit, or score the AI readiness of a repo.
Generate tailored AI agent instruction files via AgentRC instructions command. Produces .github/copilot-instructions.md (default, recommended for Copilot in VS Code) plus optional per-area .instructions.md files with applyTo globs for monorepos. Use after running /acreadiness-assess to close gaps in the AI Tooling pillar.
Help the user pick, write, or apply an AgentRC policy. Policies customise readiness scoring by disabling irrelevant checks, overriding impact/level, setting pass-rate thresholds, or chaining org baselines with team overrides. Use when the user asks about strict mode, AI-only scoring, custom weights, CI gating, or wants org-wide standardisation.
Use this skill when the user shares ad campaign performance data and asks what to cut, scale, or test. Trigger for prompts like "analyze my ad campaigns", "where am I wasting ad spend", "reallocate my ad budget", "which ads are actually working", or "ROAS analysis". Do not trigger for campaign planning or creative generation without performance data.