Performs a comprehensive Well-Architected review of Amazon DocumentDB clusters. Evaluates cluster configuration against 6 pillars (Reliability, Security, Operational Excellence, Performance Efficiency, Cost Optimization, Sustainability), generates findings with remediation guidance, and produces a universal JSON export + interactive HTML dashboard.
icon
🏗️
trigger
I need to do a DocumentDB well-architected review
inputs
[{"name":"cluster_identifier","description":"The DocumentDB cluster identifier to review","type":"string","required":true},{"name":"aws_region","description":"AWS region where the cluster resides","type":"string","required":true,"default":"us-east-1"}]
depends-on
["aws-api"]
tools
["call_aws","run_python","file_write"]
1. Overview
Performs a comprehensive Well-Architected review of an Amazon DocumentDB cluster across 6 AWS Well-Architected pillars: Reliability, Security, Operational Excellence, Performance Efficiency, Cost Optimization, and Sustainability. Evaluates 38 automated checks against live cluster configuration, CloudWatch metrics, and security posture. Produces a health score, prioritized findings with remediation CLI commands, Bedrock-generated pillar recommendations, a Universal WAR Export JSON file, an interactive HTML dashboard, and (inside Prism) a PDF export.
This is a sub-skill of the Prism platform (see the top-level prism-dash
skill). It owns cluster assessment and pillar scoring. Conversational advice and
per-query tuning are owned by the documentdb-advisor skill — defer chat/advisory
questions there.
Two execution modes
Prism Dash plugin execution — the live app runs the checks via the
wa_checks/ plugin registry (Section 4a) and renders results in the UI, with
Bedrock recommendations and PDF export. This is the primary mode.
Standalone manual execution — an agent with AWS CLI access can perform the
review directly using the 13-step workflow in Section 3 and the check catalog in
Section 4. Both modes share the same check IDs so findings are traceable.
2. DocumentDB Engine Context
The reviewing agent MUST know these facts:
DocumentDB is NOT MongoDB — API-compatible but purpose-built storage engine with B-tree indexes
Only 2/3 of instance RAM is available for buffer cache (1/3 reserved by DocumentDB)
Write to file: war_export_{cluster_identifier}_{timestamp}.json
Step 12: Generate interactive HTML dashboard
Self-contained HTML with embedded CSS
6-pillar grid layout with pillar colors
Health score header bar
Per-pillar panels grouped by status (fail first, then warn, then pass)
Write to file: war_dashboard_{cluster_identifier}_{timestamp}.html
Step 13: Present findings summary
Report health score
List all CRITICAL and HIGH severity findings
Provide top 3 remediation actions
4. Check Catalog
38 checks across 6 pillars. Of these, 37 are registered in the wa_checks/
plugin registry via the @register_check decorator; PERF1b is contributed by
the Prism database-level path (tabs/well_architected._run_db_checks) and merged
into the same result set. All check IDs are stable — use exactly what the code
defines (e.g. REL1a not REL-1, PERF1b not PERF-1b).
The complete catalog is broken down by pillar in the pillars/ directory. Each file
contains the full check table with IDs, thresholds, API calls, and remediation commands.
Read each pillar file for the detailed evaluation logic.
Note: the Prism UI may surface additional exploratory checks beyond this
canonical catalog (e.g. PERF1, PERF1c, PERF10, PERF16, COST4, plus
tabs/wa_v2/ checks) from the legacy/next-gen paths. Those are app extras; the
38-check catalog above is the source of truth for exports and scoring.
4a. The wa_checks/ Plugin Registry (wa_checks/registry.py)
In Prism, checks self-register with a decorator and are executed by run_checks().
This is the authoritative implementation of the catalog.
CheckContext fields passed to every check: cluster_id, region, cluster
(describe_db_clusters dict), instances (describe_db_instances list), analysis_data,
conn_str, shared boto3 clients docdb_client / cw_client / ec2_client, and the
per-instance fields current_instance and is_writer.
run_checks(...) execution model:
Determines writer instance IDs from cluster["DBClusterMembers"] where
IsClusterWriter is true.
Runs all non-per-instance checks first, pillar by pillar (in fixed pillar order),
sorted by priority. A check with requires_analysis=True and no analysis_data
emits an info row ("requires Analyze") instead of running.
Then iterates each instance, setting ctx.current_instance / ctx.is_writer, and
runs per-instance checks, honoring writer_only (e.g. REL9 MVCC) and
reader_only (e.g. COST9 idle readers).
A check that raises is caught and recorded as a warn row rather than aborting the
run.
Returns a flat list of result dicts: {"pillar", "id", "label", "status", "detail"}
with status ∈ {pass, warn, fail, info}.
tabs/well_architected._run_wa_checks calls run_checks() (plugin path), then appends
the database-level checks from _run_db_checks(analysis_data) (which contributes
PERF1b plus app extras), then triggers AI recommendations (Section 4b). If the plugin
import fails, it falls back to a legacy inline path producing the same IDs.
4b. Bedrock Recommendation Generation
After checks run, _generate_ai_recommendations(check_results, cluster_id, region, analysis_data) sends the failing/warning checks to Bedrock using the system prompt in
wa-advisor-prompt.md (loaded via _load_wa_advisor_prompt()). Models:
us.anthropic.claude-sonnet-4-20250514-v1:0 (primary) →
us.anthropic.claude-haiku-4-5-20251001-v1:0 (fallback). The prompt returns JSON
keyed by pillar, each entry {check_id, action, why, impact, priority} where
priority ∈ {Critical, High, Medium, Low}. Only pillars with failing/warning checks
appear; the model must not invent checks not present in the input. Recommendations are
generated asynchronously and stored in _wa["ai_md"].
Engine version classification: deprecated (3.x, 4.x), current (5.0), latest (8.0)
CloudWatch lookback: 7 days for all metrics, 13 days for failover events
CloudWatch period: 3600 seconds (1 hour) for all metrics except DatabaseCursorsTimedOut (86400 = daily)
6. Universal WAR Export Schema
{"schema_version":"1.0","metadata":{"service":"documentdb","cluster_id":"","account_id":"","region":"","engine_version":"","timestamp":"","skill_name":"documentdb-well-architected-review","checks_evaluated":0,"instances_reviewed":0},"scoring":{"overall_health_score":0,"by_status":{"pass":0,"warn":0,"fail":0,"info":0},"by_pillar":{}},"findings":[{"finding_id":"<unique UUID>","check_id":"REL1a","pillar":"reliability","check_name":"Backup retention period","status":"pass|warn|fail|info","severity":"CRITICAL|HIGH|MEDIUM|LOW","detail":"Human-readable finding with actual values","instance_id":null,"remediation_cli":"aws docdb modify-db-cluster ...","recommendations":[]}]}
Note: check_id uses the SAME IDs as the Dash app (REL1a, SEC2, PERF5, etc.). The pillar field uses lowercase with underscores (reliability, security, operational_excellence, performance_efficiency, cost_optimization, sustainability).
7. Dashboard Specification
Self-contained HTML file with embedded CSS (no external dependencies except CDN-loaded Plotly)
Dark theme with AWS-inspired color palette
Header: cluster_id, region, engine version, timestamp, health score (large, colored)
Each pillar panel: header with icon + name + status counts, body grouped by status (fail first with red left border, warn with orange, pass with green)
Each finding row: status symbol + check_id (monospace) + label + detail (muted)
Responsive layout (collapses to single column on mobile)
These four levels are used consistently across all Prism skills. The Bedrock
recommendation output (Section 4b) uses these exact priority values.
Critical: Data loss risk, security breach risk, cluster unavailability (e.g. deletion protection off, encryption disabled, single instance with no failover, MVCC IDs <25%)
High: Significant performance degradation or cost waste actively occurring (e.g. buffer cache <95%, no CloudWatch alarms, swap usage, TLS disabled)
Medium: Best practice gap with moderate risk (e.g. missing Secrets Manager, non-Graviton instances, no profiler logging, oversized instances)
Low: Optimization opportunity with low urgency (e.g. compression not enabled, cost allocation tags missing, engine upgrade available, storage type informational)
Separately, each check row carries a status of pass | warn | fail | info. The
health score (Section 3, Step 10) excludes info rows from the denominator.
9. Lessons Learned / Anti-Patterns
Always check engine version before recommending ZSTD compression (8.0+ only; use LZ4 for 5.0)
Connection limit checks must match the EXACT instance type (db.r6g.large ≠ db.r6g.xlarge)
BufferCacheHitRatio below 99% does NOT automatically mean the instance is undersized — check if the working set genuinely exceeds available cache
NEVER recommend dropping the _id index
Per-instance checks MUST identify writer vs reader roles. In the registry this is the writer_only / reader_only flags on @register_check, resolved from DBClusterMembers.IsClusterWriter (REL9/MVCC is writer_only, COST9/idle is reader_only)
Use EXACT check IDs from the code — never invent new numbering (REL1a not REL-1, PERF1b not PERF-1b)
Silent checks (REL7, REL8) should only produce findings when problems are detected — do not emit a "pass" row
FreeableMemory is compared against INSTANCE_RAM_GIB lookup — not a fixed threshold
The health score formula excludes "info" status findings from the denominator
requires_analysis=True checks (COST3, PERF8, PERF9, PERF15, SUST2) emit an info "requires Analyze" row when no analysis_data is present — they do not fail
PERF1b is not a registry check — it comes from the database-level path; keep it in the catalog but don't expect a @register_check("PERF1b", ...) decorator
10. Relation to Prism Dash App
This skill is executed by the Prism Dash app through the wa_checks/ plugin
registry (Section 4a), which is the authoritative implementation of the check catalog.
The app adds capabilities on top of the raw checks:
Live database-level analysis (index health, compression, bloat) feeds
analysis_data, enabling requires_analysis checks (COST3, PERF8, PERF9, PERF15,
SUST2) and the PERF1b redundant-index check.
AI recommendations via Amazon Bedrock and wa-advisor-prompt.md (Section 4b).
Historical trend tracking via agent_memory (wa_results.json + .v1/.v2
versions, compared by load_wa_results_previous).
PDF export via wa_pdf.generate_wa_pdf(results, ai_data, cluster_id, region) —
a cover page with health score, per-pillar sections grouped by status, and an AI
recommendations section.
Optional Universal WAR Export (Section 6) for cross-tool interoperability.
The autonomous agent (top-level prism-dash skill) runs this review as its
well_architected module. Both the standalone skill and the Dash app share the same
check IDs (REL1a, SEC1b, PERF5, …) so findings are traceable across execution modes.
Consult the references/ directory for detailed DocumentDB-specific knowledge when generating recommendations. (These are the same reference docs used by the documentdb-advisor skill; do not duplicate their content here.)
