/aws-well-architected-review

name: aws-well-architected-review
description: Performs a full AWS Well-Architected Framework review evaluating every framework question across all pillars discovered from the live AWS documentation by analyzing code, IaC, and configurations to produce evidence-backed findings with Eisenhower-prioritized remediation. Supports full reviews (every framework best practice with BP ID citations), quick reviews (question-level), pillar-scoped reviews, score-mode reviews (a maturity scorecard with per-pillar scores and filtered findings), and lens-specific reviews using lenses discovered from the live AWS documentation. Triggers on mentions of Well-Architected review, WA review, WAR, pillar assessment, architecture review across pillars, workload assessment, cloud readiness evaluation, or a Well-Architected score, grade, or scorecard request. Does not apply to single-pillar deep-dives, learning WA concepts, ADRs, or migration readiness assessments.

Well-Architected Review

Overview

Guides a systematic AWS Well-Architected Framework (WA Framework) review: discover the workload from code and IaC, acquire the live corpus inventory, evaluate every framework question and best practice against evidence, and deliver a risk-ranked, Eisenhower-prioritized report inline.

Framework content is fetched from the live AWS documentation at review time rather than embedded as a snapshot. The AWS MCP server's documentation reader (`aws___read_documentation`) is recommended for reliable retrieval; when it is unavailable, fetch the same `docs.aws.amazon.com` pages over HTTPS with the environment's web-fetch tool, and if no documentation access exists at all, proceed from internal knowledge and disclose that the framework inventory could not be verified live. Do not depend on any non-public or internal best-practice/WA-guidance MCP; those are unavailable in supported runtimes.

Detailed procedures live in reference files — read each one when its step says to:

• [Review modes](references/review-modes.md) — mode selection (full / quick / pillar-scoped / score), trigger phrases, score output format
• [Discovery procedure](references/discovery-procedure.md) — infrastructure and application architecture discovery
• [Live corpus inventory](references/phase-live-inventory.md) — the gated `ACQUIRE_CORPUS` stage: deterministic read-only traversal of the framework, the corpus records, and the validation gate
• [Evaluation procedure](references/evaluation-procedure.md) — evaluating every BP against the frozen manifest, per-pillar passes, aggregation rules, coverage audit
• [Lens guidance](references/lens-guidance.md) — when and how to apply Well-Architected Lenses
• [Risk assessment](references/risk-assessment.md) — impact × likelihood matrix and cross-pillar trade-offs
• [Report template](assets/report-template.md) — the full report structure for the report step
• [Security considerations](references/security-considerations.md) — secure handling of workload data, review tooling, findings, and persisted artifacts

Execution model

**Before beginning any step**, read and follow [security considerations](references/security-considerations.md) — secrets redaction, HTTPS-only retrieval, least privilege, and confidentiality handling must be loaded before you operate on workload code or review tooling.

A full review runs as a gated sequence. Each step has a transition gate; you MUST NOT advance to the next step, or skip a step, when its gate has not passed. The single user-visible deliverable is one complete inline report — scratch files (a run-local working directory) are execution state only, never the delivered artifact, and their paths MUST NOT appear in the report.

**Non-interactive by default.** When the user has explicitly requested a review and supplied sufficient scope, execute every step to completion **without pausing for confirmation between steps**. The discovery and risk-assessment checkpoints are **internal validation gates**, not user stops: validate them yourself and proceed. Pause for the user only when the user explicitly asked for interactive checkpoints, or when a required scope decision genuinely cannot be inferred (e.g. an ambiguous pillar-scoped request).

**Non-negotiable invariants — ALL modes (full / quick / pillar-scoped / score):**

• Step 4 (`ACQUIRE_CORPUS`) is **mode-independent**: every mode acquires and **validates** the live corpus inventory before any assessment and reads its questions/BPs against that frozen manifest. Assessment MUST NOT begin against an incomplete or unvalidated manifest, and no mode may skip Step 4.
• Canonical IDs only — never fabricate a `PILLAR##-BP##` ID. If corpus acquisition cannot produce an ID, that is a surfaced error, not a gap to invent around.

**Non-negotiable invariants — full review only:**

• Every BP in the frozen manifest receives exactly one status from the five-value vocabulary.
• **All sections of [the report template](assets/report-template.md) are present** (it is the authoritative list — the numbered items in Step 7 are the recall-critical subset, NOT the complete set: the template also mandates the Executive Summary, Architecture Overview, Cross-Pillar Trade-offs, Next Steps, and others). The report is emitted **inline**, first line `# Well-Architected Review:`. No "see file", attachment, or scratch-path deferral.

Step 1: Define the workload scope

Establish the workload from what the user provided:

> - **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)

If the user has already provided architecture details or you are in a codebase with IaC, proceed with discovery without prompting. When no code or IaC is available (the user describes their architecture verbally), proceed using the description as evidence; mark findings you cannot verify in code as "Based