AWS Well-Architected Review Skill

AWS Well-Architected Review

This workflow performs a structured AWS Well-Architected Framework (WAF) review against your workload's IaC files and deployed infrastructure. It identifies risks across all 6 WAF pillars and creates GitHub issues to track remediation.

Prerequisites

AWS CLI configured and authenticated
IaC files present in the repository (Terraform, CloudFormation, CDK, or SAM)
GitHub MCP server configured and authenticated

Workflow Steps

Step 1: Load Well-Architected Framework Reference

Fetch current AWS WAF best practices:

https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html
Pillar-specific lenses relevant to the workload type (Serverless, SaaS, etc.)

Step 2: Discover IaC & Architecture

Scan the repository for IaC files:

Terraform: **/*.tf
CloudFormation/SAM: **/*.yaml, **/*.json (CFn templates)
CDK: lib/**/*.ts, bin/**/*.ts, cdk.json

Identify key AWS services in use (compute, data, networking, security, observability) and generate a Mermaid architecture diagram.

Step 3: Pillar-by-Pillar Review

Pillar 1: Operational Excellence

[ ] All infrastructure defined as IaC (no manual console changes)
[ ] Consistent tagging strategy applied across all resources
[ ] CloudWatch alarms defined for key metrics
[ ] Automated deployment pipeline present (no manual deployments)
[ ] CloudTrail enabled for audit logging
[ ] Runbooks or operational documentation present

Pillar 2: Security

[ ] IAM roles use least-privilege policies (no * actions without justification)
[ ] No hardcoded credentials in IaC or code
[ ] Secrets managed via Secrets Manager or SSM Parameter Store
[ ] S3 buckets have public access blocked and server-side encryption enabled
[ ] Sensitive resources placed in private subnets
[ ] Security groups restrict inbound to minimum required ports/CIDRs
[ ] KMS encryption enabled for sensitive data stores (RDS, EBS, S3, SQS, DynamoDB)
[ ] SSL/TLS enforced on all endpoints (enforceSSL: true)
[ ] GuardDuty enabled (aws guardduty list-detectors)
[ ] AWS WAF configured on public-facing APIs and CloudFront distributions
[ ] MFA delete enabled on critical S3 buckets

Pillar 3: Reliability

[ ] Multi-AZ deployments for production databases (RDS Multi-AZ, DynamoDB Global Tables)
[ ] Auto Scaling configured with appropriate policies for EC2/ECS
[ ] S3 versioning and lifecycle policies configured
[ ] RDS automated backups enabled with appropriate retention period
[ ] DynamoDB Point-in-Time Recovery (PITR) enabled
[ ] Dead Letter Queues (DLQ) configured for Lambda, SQS, SNS
[ ] Route 53 health checks configured for DNS failover
[ ] Lambda reserved concurrency set to prevent noisy-neighbor throttling

Pillar 4: Performance Efficiency

[ ] Right-sized instance types (Lambda memory, EC2 type, RDS class)
[ ] Graviton/ARM instances used where available (Lambda arm64, EC2 Graviton)
[ ] Caching implemented (ElastiCache, DAX, CloudFront, API Gateway caching)
[ ] CloudFront used for global static content delivery
[ ] Aurora Serverless or DynamoDB On-Demand for variable load patterns
[ ] Lambda Provisioned Concurrency for latency-critical synchronous paths

Pillar 5: Cost Optimization

[ ] EC2 Reserved Instances or Savings Plans for steady-state workloads
[ ] S3 lifecycle policies moving data to cheaper storage tiers
[ ] Lambda arm64 architecture adopted (20% cost reduction)
[ ] VPC Endpoints for S3/DynamoDB to avoid NAT Gateway charges
[ ] gp2 EBS volumes migrated to gp3 (same performance, 20% cheaper)
[ ] Development/test environments have auto-shutdown schedules
[ ] AWS Budgets and Cost Anomaly Detection configured
[ ] Unattached EBS volumes and idle EC2 instances identified

Pillar 6: Sustainability

[ ] Graviton/ARM instances selected where available
[ ] Serverless/managed services preferred over always-on EC2
[ ] S3 lifecycle policies reduce unnecessary long-term data storage
[ ] Auto Scaling configured to avoid over-provisioning
[ ] Region selection considers AWS renewable energy commitments

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

🏗️ AWS Well-Architected Review Summary

📊 Review Results:
• IaC Files Analyzed: X
• AWS 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)

Step 6: Create Individual Finding Issues

Label with "well-architected" and the pillar name (e.g., "security", "reliability").

Title: [WAF-<PILLAR>] [Brief Finding] — [Risk Level]

Body:

## 🏗️ Well-Architected Finding: [Brief Title]

**Pillar**: [Name] | **Risk Level**: [High/Medium/Low] | **Effort**: [Low/Medium/High]

### 📋 Description
[Clear explanation of the finding and why it matters]

### 🔧 Remediation

**IaC Fix** (preferred):
```hcl
# Terraform example
resource "aws_s3_bucket_server_side_encryption_configuration" "example" {
  bucket = aws_s3_bucket.example.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "aws:kms"
    }
  }
}
```

**AWS CLI fallback**:
```bash
aws s3api put-bucket-encryption --bucket <name> \
  --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms"}}]}'
```

### 📚 AWS Reference
- [WAF Best Practice Link]
- [AWS Documentation Link]

### ✅ Validation
- [ ] Change implemented in IaC and deployed
- [ ] AWS Config rule passes (if applicable)
- [ ] Security Hub finding resolved (if applicable)

**Well-Architected Question**: [WAF question this maps to]

Step 7: Create EPIC Tracking Issue

Label with "well-architected" and "epic".

Title: [EPIC] AWS Well-Architected Review — X findings across 6 pillars

Body: Executive summary with pillar breakdown table (finding counts by pillar and risk level), Mermaid architecture diagram, prioritized checklist linking all individual issues (High → Medium → Low), and success criteria:

All High-risk findings resolved
Medium findings have accepted mitigation plans
No regression in existing CloudWatch alarms or Config rules

Error Handling

No IaC Files Found: Limit review to live resource discovery via AWS CLI and note the gap
Insufficient AWS Permissions: List required read-only permissions for the review
GitHub Creation Failure: Output all findings as formatted markdown to console

Success Criteria

✅ All 6 WAF pillars reviewed against IaC and live infrastructure
✅ All findings classified by risk level and pillar
✅ Actionable remediation steps with IaC examples for each finding
✅ GitHub issues created for team tracking
✅ Architecture diagram generated for EPIC context
✅ AWS documentation references included

Agent Skills: AWS Well-Architected Review

Install this agent skill to your local

Skill Files