# Architecture Decision Stress-Test Guide

Use this reference for cross-domain AWS solution architecture decisions, ADRs, tradeoff reviews, target architectures, and production-readiness stress testing.

## What people get wrong

The lazy story is:

> Pick the AWS best-practice pattern and fill in the diagram.

Wrong. Architecture is tradeoff management under constraints. A design is not good until assumptions, failure modes, owners, validation paths, and rollback/migration paths survive scrutiny.

Common bad assumptions:

- Serverless, containers, or managed services are always the right default.
- A Well-Architected answer is enough without evidence.
- Security, reliability, cost, and delivery tradeoffs can be optimized independently.
- Multi-Region is always more resilient.
- Architecture diagrams show data boundaries, quotas, or operational ownership.
- Future flexibility justifies complexity now.

## Architecture-specific failure modes

- Missing workload context: users, data sensitivity, SLOs, RTO/RPO, traffic, regulatory needs, and team capability.
- Hidden coupling through IAM roles, KMS keys, DNS, event schemas, shared VPCs, databases, queues, and CI/CD.
- Control-plane dependencies are mistaken for data-plane resilience.
- Operational model lacks observability, runbooks, cost accountability, support plan, or ownership.
- Migration path lacks strangler steps, rollback point, data cutover, or coexistence design.
- Design optimizes a favorite service rather than stated constraints.

## Minimum safe workflow

1. Restate problem, constraints, non-goals, assumptions, and decision drivers.
2. Identify workload domains: identity, network, compute, data, integration, observability, security, resilience, cost, and delivery.
3. Compare at least two viable options when the decision is material.
4. Stress-test each option against failure modes, data boundaries, quotas, operational ownership, migration, rollback, and cost.
5. Choose the minimum viable architecture that satisfies constraints; call out rejected complexity.
6. Produce an ADR-style decision: context, options, decision, consequences, risks, validation plan, and revisit triggers.
7. Route single-domain deep work to narrower AWS skills when needed.

## Verification targets

- workload context: users, traffic, data classification, compliance, SLO/RTO/RPO, cost target, and team capability
- architecture diagram plus trust/data boundaries, network paths, identity paths, and event/data flows
- dependency inventory for managed services, third parties, DNS, KMS, shared accounts/VPCs, and pipelines
- Well-Architected pillar impacts, risks, and explicit tradeoffs
- validation plan: load test, threat model, DR test, cost model, proof of concept, migration rehearsal, and rollback criteria
- implementation roadmap with owners, milestones, guardrails, and decision revisit date

## When to push back

Push back if the user asks to:

- rubber-stamp a preferred architecture without alternatives
- add multi-Region, Kubernetes, microservices, or AI because it sounds modern
- ignore data classification, IAM, cost, or recovery constraints
- produce a diagram without operating model and validation plan
- treat official best practices as proof that this workload is ready
- design beyond team capability or budget without naming the risk

# Official sources

Use this reference only when you need source grounding for AWS service behavior or the detailed source list.

## AWS documentation

Use these as starting points, not as proof of the user's live AWS state:
- https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html
- https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/welcome.html
- https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/welcome.html
- https://docs.aws.amazon.com/wellarchitected/latest/cost-optimization-pillar/welcome.html

## Grounding rule

Official documentation explains AWS service behavior. It does not prove the user's current account, Region, quota, resource configuration, IAM boundary, pricing, entitlement, or operational state. Prefer read-only AWS MCP or CLI evidence, repository evidence, or sanitized user-provided evidence for current-state claims.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:
- The AWS Well-Architected Framework helps evaluate tradeoffs and best practices for reliable, secure, efficient, and cost-effective cloud systems.
- Security, reliability, and cost optimization pillars each provide separate guidance; a solution decision can improve one pillar while increasing risk in another.

Sampled live evidence:
- Read-only regional availability sampling reported `WellArchitected+GetWorkload` as `isAvailableIn` in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.

Review implications:
- Architecture recommendations must state workload context, constraints, assumptions, tradeoffs, pillar impacts, validation path, and migration/rollback path.
- Well-Architected tool/API availability does not prove a workload has been reviewed or that risks are remediated.

# Safety checklist

Use this reference before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting recommendations.

## Non-negotiables

- Never ask users to paste secrets, access keys, session tokens, private keys, customer identifiers, or sensitive account data into chat.
- Use read-only AWS MCP or read-only AWS CLI evidence for live state when available; otherwise use repository evidence, sanitized user evidence, or official documentation and label the evidence level.
- Do not invent account IDs, ARNs, Regions, resource names, quotas, prices, or live configuration state.
- Require explicit user approval before privileged, destructive, traffic-changing, cost-changing, or production-impacting actions.
- Use current official AWS documentation for service behavior when the answer depends on AWS service details.
- Keep remediation least-privilege, reversible, and scoped to the requested workload or account boundary.

## Stress checks

- What can expose data?
- What can escalate privilege?
- What can break production or block rollback?
- What can create unbounded cost?
- What compliance or audit evidence is missing?
- What rollback or validation path is unproven?

## Evidence labels

Use `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`. Documentation alone never proves the user's live AWS state.

# Workflow and output contract

Use this reference only when performing the full review, implementation guidance, incident triage, or production-readiness pass.

## Review domains

Check these areas before giving a verdict:
- Business goal, workload criticality, data classification, RTO/RPO, and region strategy
- Account and OU placement, identity model, blast radius, and governance controls
- Network topology, ingress/egress, private connectivity, DNS, segmentation, and inspection
- Compute, data, storage, observability, security, reliability, operations, and cost posture

## Safe workflow

1. **Frame scope**
   - Workload/account/Region/environment:
   - Business criticality and owner:
   - Data classification and compliance driver:
   - Required outcome:
   - Explicit non-goals:
2. **Collect evidence**
   - Prefer read-only AWS MCP or read-only AWS CLI evidence for current-state claims when available.
   - Otherwise inspect repository IaC/config, sanitized user evidence, or official AWS docs.
   - Label each finding as `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`.
3. **Stress-test risk**
   - What can expose data?
   - What can escalate privilege?
   - What can break production or block rollback?
   - What can create unbounded cost?
   - What evidence is missing?
4. **Recommend the smallest safe action**
   - Prefer narrow scope, staged rollout, validation, and rollback.
   - If the safest action is to stop and gather evidence, say that plainly.

## Output contract

Return this structure:
```markdown
# AWS Solution Architect: <scope>
## Executive verdict
- Status: READY / READY WITH RISKS / NOT READY / NEEDS EVIDENCE
- Biggest risk:
- Evidence level:
## Scope and assumptions
- Confirmed:
- Unknown:
- Out of scope:
## Findings
| Severity | Finding | Evidence | Why it matters | Minimum safe action |
|---|---|---|---|---|
## Recommended actions
1. <action> — owner: <owner>, validation: <check>, rollback: <rollback>
## Validation
- Commands or checks:
- Expected result:
## Residual risk
- <risk or explicit none>
```