wa-builder

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: wa-builder
description: '"Learn then Build" — help developers understand AWS Well-Architected best practices for their specific workload, then produce actionable visual artifacts (architecture diagrams with WA annotations, decision trees, improvement roadmaps) they can commit and use. Adapts explanations for beginners and generates artifacts faster for experienced builders. Use when the user wants to understand WA for their project, create architecture diagrams with pillar health overlays, get guided decision flows for architectural choices, or generate a visual improvement roadmap.'
not_for: assessments or reviews that produce findings (use aws-well-architected-framework-review), migration planning (use migration-readiness), generating guardrails (use wa-guardrails), facilitating a WAFR (use wafr-facilitator)
version: 1.0.0
---

# Well-Architected Builder

## Overview

This skill helps developers **understand** Well-Architected for their specific workload and **produce visual artifacts** they can commit. Unlike aws-well-architected-framework-review (which assesses and scores), wa-builder teaches and enables.

**What you'll produce:**
1. Architecture diagram with WA annotations (color-coded pillar health, risk hotspots)
2. Decision trees for architectural choices (contextual trade-off flowcharts)
3. Improvement roadmap (Gantt timeline + dependency graph)

### Knowledge base

This skill uses the AWS Well-Architected Framework (6 pillars, 57 questions) as its knowledge base. It does NOT require external framework files — all guidance is derived from the WA Framework questions and design principles embedded in this skill's instructions.

## Step 1: Context and Calibration

Ask the user:

> I can help you understand Well-Architected for your project and produce visual artifacts. Let me know:
> - **Workload name** and brief description (or point me at your code)
> - **Your WA familiarity**: New to WA / Familiar / Practitioner
> - **What you want**: Architecture diagram, decision tree, roadmap, or all three
> - **Existing review** (optional): If you have a aws-well-architected-framework-review output, share it for richer artifacts

If context is already provided or you're in a codebase, proceed directly.

### Experience detection

If the user doesn't explicitly state familiarity, detect from language:
- Uses "pillar", "HRI", "RTO/RPO", "blast radius" naturally → **Practitioner**
- Asks "what is WA" or "how does this apply" → **Beginner**
- Default → **Familiar**

### Adaptive behavior

| Phase | Beginner | Familiar | Practitioner |
|-------|----------|----------|--------------|
| Learning | Full pillar explanations with analogies | Concise pillar relevance | Skip → artifacts |
| Discovery | Guided questions with examples | Direct questions | Accept shorthand |
| Artifacts | Explain each annotation | Brief legend | Raw artifacts only |
| Decision trees | Include "what does this mean?" nodes | Standard decision flow | Compact trade-off matrix |

## Step 2: Workload Discovery

### Path A — Standalone (no prior review)

Perform a lightweight discovery:
1. Scan IaC files for resource types and configurations
2. Identify primary compute pattern (serverless, containers, VMs, mixed)
3. Identify data stores and persistence patterns
4. Identify network topology and external integrations
5. Identify deployment and operations patterns

Produce a **workload profile**:
- Architecture pattern (microservices, monolith, event-driven, etc.)
- AWS services in use
- Per-pillar health signals (3-5 strongest indicators per pillar)
- Top 3 risk hotspots

### Path B — Post-review (consumes aws-well-architected-framework-review output)

Parse the aws-well-architected-framework-review report to extract:
- Pillar scores (1-5) from the scorecard
- Findings by severity (Critical, High, Medium, Low)
- Evidence locations (file:line)
- Remediation plan items
- Architecture diagram (if PlantUML was generated)

Use this directly — skip lightweight discover