/aws-well-architected-framework-review

name: aws-well-architected-framework-review
description: Perform a full AWS Well-Architected Framework review evaluating all 57 questions across 6 pillars by analyzing code, IaC, and configurations to produce evidence-backed findings with Eisenhower-prioritized remediation.
not_for: single-pillar deep-dives (use the specific pillar skill), learning WA (use wa-builder), ADRs (use architecture-decision-record), migration (use migration-readiness)
version: 2.3.0

> [!NOTE] > **Deprecated.** This skill is superseded by `aws-well-architected-review` in > [Agent Toolkit for AWS](https://github.com/aws/agent-toolkit-for-aws). New > feature work is not accepted here; see > [issue #147](https://github.com/aws-samples/sample-well-architected-skills-and-steering/issues/147).

Well-Architected Review

Step 1: Define the workload scope

Ask the user to describe the workload:

> What workload would you like me to review? Please share: > - **Workload name** and brief description > - **Code packages/directories** to analyze (IaC, application code, CI/CD configs) > - **Business criticality** (critical, high, standard, low) > - **Current pain points** (optional — anything you already know is problematic)

If the user has already provided architecture details or you are in a codebase with IaC, skip the prompt and proceed with discovery.

**IMPORTANT**: When no code or IaC is available to analyze (e.g., the user describes their architecture verbally), proceed with the review based on the information provided. Produce the full report using explicit statements in the architecture description as evidence. Treat omitted details as unknown, not as evidence that a control is absent. Mark unverifiable implementation details `Cannot Determine`, state what evidence would resolve them, and do NOT ask for code if the user has already given you enough context to perform a meaningful review.

Determine if a specialized WA Lens applies:

• SaaS, Serverless, Data Analytics, Machine Learning, IoT, Containers, Games, Financial Services, Healthcare

If a lens is obvious from the code (e.g., Lambda-heavy → serverless), note it and apply lens-specific questions.

Step 2: Infrastructure Discovery

Analyze all infrastructure-as-code and deployment configurations in the codebase.

You MUST examine:

• CDK code (TypeScript, Python, Java, Go)
• CloudFormation templates (YAML, JSON)
• Terraform configurations (.tf files)
• SAM/Serverless Framework templates
• CI/CD pipeline definitions (CodePipeline, GitHub Actions, etc.)
• Monitoring configurations (CloudWatch alarms, dashboards)
• Deployment configurations (CodeDeploy, ECS deployment settings)

For each infrastructure component, document:

• Resource type, logical name, and configuration
• File path and line numbers where defined
• Security-relevant configs (IAM, encryption, network)
• Resilience configs (multi-AZ, backups, scaling)
• Cost-relevant configs (instance types, capacity mode)

Record the workload's **primary IaC dialect** (CDK, CloudFormation, Terraform, or SAM) — Step 6 emits a per-finding **Fix:** block in this dialect. When the workload has no IaC, note that fix blocks will fall back to AWS CLI commands.

You MUST create an architecture diagram in PlantUML showing:

• All major components and their relationships
• Data flows and external dependencies
• Trust and network boundaries

Step 3: Application Architecture Discovery

Analyze application code for architectural patterns:

• Entry points (API handlers, event processors, scheduled tasks)
• Service communication patterns (sync/async, retries, timeouts, circuit breakers)
• Data access patterns (queries, caching, connection management)
• Error handling and resilience patterns
• Authentication/authorization logic
• Observability instrumentation (logging, tracing, metrics)

---STOP--- **Checkpoint**: Discovery complete — present findings before evaluation.

> Here is what I discovered about your workload: > - **Infrastructure**: {summary of IaC resources found} > - **Architecture patterns**: {key patterns detected} > - **Scope**: {number of files/resources analyzed} > > **Shall I proceed with the full 57-question evaluation, or would you like to adjust the scope?**

Do NOT proceed past this point until the user explicitly confirms. ---

Step 4: Evaluate EVERY WA Framework question with code evidence

**CRITICAL — DO NOT PRODUCE A SHORT REVIEW.** The single most common failure mode is citing 20-30 BPs and stopping. The reference corpus contains **307 BPs across 57 questions**; a real full review MUST evaluate ALL 307. Every BP receives one of five statuses: Implemented, Partially Implemented, Not Implemented, Not Applicable, or Cannot Determine (with rationale). If you find yourself with fewer than 200 BP citations, you have not finished the review. Iterate until every BP is addressed.

Assess the workload against ALL 57 questions in the Well-Architected Framework. For each question, provide:

• **Status**: "Implemented", "Partially Implemented", "Not Implemented", "Not Applicable", "Cannot Determine"
• **Evidence**: specific file paths and line numbers
• **Gaps**: what's missing or could be improved
• **Risk**: what could go wrong due to the gap

Evidence sufficiency gate

Assign a status only after applying this gate:

• **Implemented** — explicit evidence demonstrates the complete BP.
• **Partially Implemented** — explicit evidence demonstrates part of the BP and identifies a concrete gap.
• **Not Implemented** — explicit evidence states the control is absent, or an authoritative and sufficiently complete source was examined where the control would have to appear and it is absent.
• **Not Applicable** — the BP is outside the workload scope; provide a workload-specific rationale.
• **Cannot Determine** — available evidence is missing, inconclusive, runtime-only, or outside the inspected scope. State the exact artifact, metric, configuration, or interview answer needed to decide.

Absence of evide