Shape recipe: FULL_ASSESSMENT

Loaded by SKILL.md Step 0 when the prompt is rich enough to warrant a structured assessment report.

What this shape is

A full migration / adoption assessment with 9 named sections, a numeric readiness score (0–100, GREEN/YELLOW/RED), inline math derivations, ≥3 timestamped citations, ≥2 named gotchas, and a Next Steps handoff (concrete pointers to other skills, CLI commands, AWS docs, and the Pricing Calculator). Output is the longest of any shape in this skill — typically 800–2,000 words depending on artifact density. The customer is asking for something they could hand to a director, an architect, or a steering committee; not a one-liner.

This shape does not include Timeline & Resourcing (engineer-weeks, calendar weeks, or "phase 1 = 2 weeks"). That section was removed from the suite — see NOT REQUIRED below. Cost estimates are also omitted; route to https://calculator.aws.

When to dispatch here (detection signals)

Pick this shape when ≥2 of the following are true. If only ONE is true, prefer a more focused shape (focused-operational, schema-conversion, sizing-only).

Strong signals (any one is sufficient):

Phrases: "produce an assessment", "give me a full assessment", "complete migration plan", "end-to-end report", "write up a recommendation", "prepare a doc for my director / architect / VP".
Customer pasted ≥2 substantial artifacts: schema.xml + solrconfig.xml, _cat/indices + _cluster/health + _nodes/stats, or any combination of ≥40 lines of structured config.
Customer specifies workload context AND constraints AND a goal in the same prompt (e.g., "30 indexes, 4 TB, 8k QPS peak, GDPR, must finish before Q3, recommend the path").

Weaker signals (need a second one):

Mention of source engine + version + region + scale numbers (docs / GB / QPS).
Multiple personas implied ("for our DevOps and search-relevance teams").
Mention of compliance, SLA, or audit context (HIPAA, PCI, SOC2, FedRAMP, GDPR, multi-region DR).
Explicit ask for a readiness score, risk register, or gap analysis.

Counter-signals (do NOT dispatch here):

Question fits in one sentence with no artifacts → overview or focused-operational.
Single artifact, single ask (e.g., "map this schema") → schema-conversion.
Pure A-vs-B decision → comparative-decision.
Wrong-fit migration (Postgres + transactional + small) → anti-pattern-pushback.

Required output template

Begin with the report title (# Migration Assessment: <name>), then a single fenced metadata header showing the generated time and skill version, then the 9 sections.

Header (mandatory — placed immediately after title, before §1)

Call the current_time tool (returns ISO 8601 UTC) and read the skill version from the version: field in SKILL.md frontmatter. Emit:

> Generated: 2026-06-02T16:45:30Z | Skill: amazon-opensearch-service v1

If the current_time tool is unavailable, fall back to a placeholder <UTC ISO 8601> and call this out — never invent a timestamp.

9 sections

Produce these 9 sections, in this order, with these names. Each section header is a level-2 heading (##).

1. Executive Summary (3–5 bullets, ~80 words)

Source restatement (engine + version + scale) — first sentence.
Recommended target shape (Managed vs Serverless NextGen vs Classic) + recommended migration tool.
Readiness score with tier: e.g., 74/100 — YELLOW.
One named risk-blocker or top migration specific (cite gotcha # if applicable).
Pricing handoff line: "plug sizing into https://calculator.aws for monthly cost".

2. Source

A 4–8-row table: engine, version, post-fork status, total docs, total GB, index count, plugin/custom-lib count, fork-rule applicability. Mark UNKNOWN explicitly — do NOT invent values. If artifact density is rich, include a collapsible JSON fingerprint.

3. Target

Recommended deployment: Managed Multi-AZ-with-Standby / Managed Multi-AZ / Serverless NextGen / Serverless Classic. State the decision driver (e.g., "Multi-AZ-with-Standby because 99.95% SLA was named", "Serverless NextGen because <100 GB vector workload with bursty traffic"). Name the engine version target (OS 2.19 or OS 3.x) and the upgrade-path implication.

4. Migration Path

Frame the migration around the 3 components (see references/assessment-workflow.md § "Components of a migration"):

Historical Data Migration — required unless greenfield.
Live Traffic Migration — required only when the read-only window cannot cover the time HDM takes.
Application Code Rewrite — required for Solr → OpenSearch, X-Pack ports, language-binding swaps.

For each component the customer needs, pick ONE primary strategy in bold with a one-sentence reason, then a ranked table over the candidate strategies for that component:

Strategy	Score (0–10)	Pros	Cons

Apply the always-true rules from assessment-workflow.md (post-fork lockout, Migration Assistant for Amazon OpenSearch Service Solr-target restrictions, _source: false HDM-only, etc.). For ES ≥ 7.11 sources <100 GB with ≥30 min cutover window, the primary HDM strategy must be _reindex from remote — Migration Assistant for Amazon OpenSearch Service Historical Data Migration is overkill at that scale.

5. Sizing

Show math inline. Do not produce a single point estimate without a derivation chain. Example formula:

storage_gb_per_node = (raw_gb × (1 + replicas) × (1 + overhead_0.15) × (1 + headroom_0.25)) / data_node_count

Required outputs:

Compute: <N>× <instance_class> for data nodes (e.g., 6× r7g.2xlarge.search) — Graviton r7g/r8g default.
Cluster managers: 3× <instance> for ≥6 data nodes (e.g., 3× m7g.large.search).
Storage: GB per node + storage type (gp3 vs io2 vs Instance Store).
Shards: shard count derivation (target shard size 10–50 GB).
JVM heap implication: 50% RAM, capped at 32 GB. Cite OS 2.17+ shard-cap rule (gotcha #4) if shards/node trends >800.

If inputs are UNKNOWN, present 2–3 tiered bands (small / medium / large) — never invent a single point estimate.

6. Readiness

Numeric score 0–100, weighted breakdown across these 7 dimensions:

Dimension	Weight
Compatibility	25%
Operational readiness	15%
Sizing fitness	15%
Data movement complexity	15%
Cutover complexity	10%
Sizing-input completeness	10%
Stakeholder alignment	10%

Tier rule:

GREEN ≥80 — proceed; surface top items to flag in §7 (split across Migration specifics and Risks/blockers).
YELLOW 60–79 — run a PoC + spike on the lowest-scoring dimension before committing.
RED <60 — do not commit; weakest dimension first.

7. Risks & migration specifics

Two-table section. Citations into references/assessment-gotchas.md are by gotcha number (e.g., "#2 — ES ≥ 7.11 snapshot/restore lockout"). For Solr sources, prefer #1, #11, #12. For ES sources, prefer #2, #3. For vector workloads, prefer #7, #10.

Migration specifics — items with a known, well-trodden remediation. Frame these as "this is how the migration handles X", not as risks. The prescribed fix is part of the path, not a hazard. Each row: gotcha number, one-line spec, the remediation in concrete terms (config change, transformer flag, alternate tool). Most #11–#13 type items, and most "Solr → OpenSearch refactor" semantics items, belong here.

Risks / blockers — items that genuinely constrain the migration: no known fix, capacity-plan implications, irreversible target choices, or dependencies on customer action that can fail late. Each row: gotcha number, severity (HIGH / MEDIUM), what breaks if unaddressed, decision needed. #1 (Solr→OS document-level), #3 (Lucene 8→10 segment wall), #16 (uw.medium k-NN), and any "no equivalent on Serverless" items typically belong here.

Include ≥2 named gotchas across the two tables. Always reflect workload-specific trade-offs the customer mentioned in the prompt — do NOT recycle a generic list. If a gotcha has a clean remediation that the migration plan already includes, it belongs in Migration specifics, not Risks.

8. Next Steps

Concrete handoffs the customer can take to ACT on this assessment. Required if a migration path is recommended. Each next step MUST be one of:

Other AWS skill / capability to load when their next question lands in that domain. Mark with the aws- prefix when applicable. Examples:
- "For the post-migration sizing PoC, load amazon-opensearch-service shape SIZING_ONLY with measured peak QPS."
- "For deploying Migration Assistant for Amazon OpenSearch Service on EKS, route to the aws-eks skill."
- "For VPC + KMS-CMK setup, route to the aws-security skill."
- "For Bedrock Titan embeddings on the RAG side-pipeline, route to amazon-bedrock (capability: knowledge-bases-setup)."
Concrete AWS / OpenSearch CLI commands the customer should run next. Examples:
- "Run aws opensearch describe-domain-config --domain-name <name> to confirm the source target region."
- "Pull Migration Assistant for Amazon OpenSearch Service prerequisites with kubectl apply -f https://raw.githubusercontent.com/opensearch-project/opensearch-migrations/main/...."
- "Run GET /_cat/plugins?v on the source cluster to inventory plugins for the gap register."
AWS docs links to the canonical procedure for the chosen path (NOT for general background — those go in Citations). Examples:
- "Migration Assistant for Amazon OpenSearch Service — solution implementation: https://docs.aws.amazon.com/solutions/latest/migration-assistant-for-amazon-opensearch-service/solution-overview.html"
- "Cluster sizing best practices: https://docs.aws.amazon.com/opensearch-service/latest/developerguide/bp.html"
AWS Pricing Calculator with the specific sizing inputs you derived. State "plug instance class + count + storage from §5 into https://calculator.aws" — not generic.
MCP / agent commands — if the user is operating an agent harness, surface relevant commands (e.g., "call the AWS MCP aws___get_regional_availability tool to verify r7g.2xlarge.search in us-west-2").

Format:

| # | Action | Pointer |
|---|---|---|
| 1 | Stand up Migration Assistant for Amazon OpenSearch Service on EKS | https://docs.aws.amazon.com/solutions/latest/migration-assistant-for-amazon-opensearch-service/solution-overview.html |
| 2 | Run sizing PoC | Load `amazon-opensearch-service` shape SIZING_ONLY with measured peak QPS |
| 3 | Plug sizing into Pricing Calculator | https://calculator.aws (use 6× r7g.2xlarge.search, 3× m7g.large.search, gp3 300 GB) |
| 4 | Provision security stack | Route to `aws-security` skill |
| 5 | Inventory source plugins | `GET /_cat/plugins?v` on source |

5–7 rows is typical. Each pointer is either a skill name, a CLI command in backticks, or a full URL. Generic "talk to your DevOps team" or "do testing" entries do NOT count — point at a specific resource.

9. Citations

≥3 entries. Each entry must include:

Source URL (full).
Retrieval timestamp (UTC, ISO-8601 — 2026-06-02T14:32Z).
One-sentence claim summary (what version-volatile fact you used it for).

Required URLs (pick the ≥3 you actually used): the AWS best-practices page for sizing math, the AWS upgrade-path page, the Migration Assistant for Amazon OpenSearch Service doc when Migration Assistant for Amazon OpenSearch Service is recommended, the Serverless NextGen comparison page when relevant, and https://calculator.aws for the cost handoff.

NOT REQUIRED — explicitly omit

Timeline & Resourcing — REMOVED FROM SUITE. Do NOT produce a "Phase 1 = 2 weeks" table, "engineer-weeks" estimates, "critical path = …" lines, or any calendar-based commitment. If you find yourself reaching for words like "timeline", "engineer-weeks", "resourcing", "calendar", "weeks of effort", STOP and delete the section. The customer will plan timeline using their own program-management practices.
Dollar / cost estimates. No $X/month, ~$1,500, ≈ $40k/year. Hard route to https://calculator.aws.
A 6-question business intake. This shape assumes the customer already gave you the artifacts. If you find yourself wanting to ask 6 questions, the shape was probably misdetected — re-route to overview.
Per-claim inline citations. Citations are batched in section 9.
Tool narration ("I will now check…", "Let me load…"). First sentence must restate source/version/scale.

Worked exemplar (~330 words)

Detected shape: FULL_ASSESSMENT — pasted schema.xml, solrconfig.xml, and traffic numbers; explicit "prepare a doc for our architect".

Migration Assessment: Acme Search Platform

Generated: 2026-06-02T16:45:30Z | Skill: amazon-opensearch-service v1

You're on Apache Solr 8.11 SolrCloud, 3 collections, ~120 M docs, ~600 GB on disk, ~2.5k QPS sustained / 8k peak, target Amazon OpenSearch Service in us-west-2 for a Search Relevance Engineer + DevOps audience — here's the assessment.

Executive Summary. Recommend Managed OpenSearch 2.19 Multi-AZ-with-Standby, migrated via Migration Assistant for Amazon OpenSearch Service Solr backfill (Historical Data Migration) — Solr → OS is document-level only (gotcha #1), and at 600 GB the single-shot _reindex path is too slow. Readiness 72/100 — YELLOW. Top blocker: 4 custom plugin JARs in <lib> directives need port. Plug sizing below into https://calculator.aws.

Source. Solr 8.11 · 3 collections · 120 M docs · 600 GB · <uniqueKey>doc_id</uniqueKey> · 4 custom JARs · q.op=AND · 2 <copyField> · NMSLIB-equivalent: N/A.

Target. Managed OpenSearch 2.19 Multi-AZ-with-Standby (the named 99.95% SLA forces Standby; OS 2.19 chosen because OS 3.x requires reindex of any pre-2.x indexes — already moot on a refactor migration, so 2.19 is the conservative landing). Upgrade to OS 3.x is in-scope post-cutover.

Migration Path. Migration Assistant for Amazon OpenSearch Service Historical Data Migration — primary (backfill the 600 GB), with Migration Assistant for Amazon OpenSearch Service Live Traffic Migration for the cutover window. _reindex from remote scored 4/10 (Solr is not a remote source). Snapshot/Restore scored 0 (no Solr→OS snapshot path).

Sizing. (600 × 2 × 1.15 × 1.25) / 6 = 287.5 GB/node → 6× r7g.2xlarge.search + 3× m7g.large.search cluster managers, gp3 300 GB/node. 18 primary shards × 1 replica ≈ 33 GB/shard (in target band). JVM 32 GB heap → shard cap 2,000/node (gotcha #4).

Readiness. Compatibility 18/25 (custom JARs −5, q.op −2). Operational 12/15. Sizing 14/15. Data movement 9/15 (Solr is document-level only — no segment-level path). Cutover 7/10. Sizing-input 6/10 (no peak ingest rate). Stakeholder 6/10. Total 72/100 — YELLOW.

Migration specifics. #11 — if the source solrconfig.xml sets q.op=AND, set default_operator: AND on every translated query_string handler. #12 — Migration Assistant's metadata transformer strips fielddata from text fields automatically and adds the .keyword subfield.

Risks / blockers. #1 Solr→OS is document-level, not segment-level (HIGH) — the 600 GB backfill goes via Migration Assistant Historical Data Migration, no snapshot path exists. Custom JARs require port to the OS plugin API (HIGH) — not supported on Serverless NextGen, so this constrains the target.

Next Steps. (1) Deploy Migration Assistant for Amazon OpenSearch Service on EKS — https://docs.aws.amazon.com/solutions/latest/migration-assistant-for-amazon-opensearch-service/solution-overview.html. (2) Port 4 custom JARs to OS plugin API. (3) Run sizing PoC — load amazon-opensearch-service shape SIZING_ONLY with measured peak ingest rate. (4) Plug 6× r7g.2xlarge.search + gp3 300 GB into https://calculator.aws. (5) GET /_cat/plugins?v on source to complete plugin inventory.

Citations. 3 URLs with retrieval timestamps follow.

Pre-emit checklist (specific to this shape)

Tick each before sending. If any box is unchecked, fix or restart.

Metadata header present immediately after title: > Generated: <ISO 8601 timestamp> | Skill: amazon-opensearch-service v<N> — timestamp pulled from current_time tool, version from SKILL.md frontmatter.
First sentence (after the header) restates source engine + version + scale + target region + persona.
All 9 section headers present, in order, named exactly as in this recipe.
Numeric readiness score (0–100) + GREEN/YELLOW/RED tier.
Math derivation shown inline in Sizing — no naked single-point estimates without a formula.
Graviton current-gen instances (r7g/r8g, m7g/m8g) — older families only with explicit justification.
Migration Path names the required components (Historical Data Migration / Live Traffic Migration / Application Code Rewrite — only those that apply), and for each, picks ONE primary strategy in bold + a ranked table of candidate strategies.
≥2 named gotchas cited by number across §7 (Migration specifics + Risks/blockers; e.g., #2, #11).
≥3 citations in section 9, each with URL + UTC timestamp + claim summary.
Customer-specific trade-offs in §7 (not a generic recycled list).
Items with a known fix routed to Migration specifics, not lumped under Risks/blockers.
Next Steps section (§8) present with 5–7 concrete pointers — each pointer is a skill name, a CLI command, an AWS docs URL, or https://calculator.aws with derived inputs. No generic "talk to your team" entries.
NO Timeline & Resourcing section, no engineer-weeks, no calendar weeks, no Phase 1 = X weeks.
NO dollar estimates; pricing handoff line points at https://calculator.aws.
No marketing tone ("seamless", "robust", "best-in-class", "production-hardened").
UNKNOWN inputs marked explicitly OR presented as tiered bands — no invented numbers.
If the target is OS 3.x crossing from any 1.x or 2.x source: the Risks/blockers half of §7 MUST cite (a) the Lucene segment wall — "Lucene 10 cannot read Lucene 8 segments — segment format is forward-only, so every pre-2.x index must be reindexed before reaching 3.x" — AND (b) at least one named OS 3.x breaking change beyond the segment wall: JDK 21 minimum runtime, Security Manager → Java agent migration for plugins, NMSLIB engine removal (forces reindex into FAISS), or renamed k-NN settings. Both items are required when crossing the 3.x boundary. (Plain transformer-handled items go in Migration specifics.)
If the response recommends an AOS in-place upgrade: the mechanism is named blue/green (the literal word) at least once. Do NOT describe it as a "long minor-version chain" or invent step-by-step minor hops (e.g., 2.5 → 2.7 → 2.9 → 2.11 → 2.19). AOS supports multi-version blue/green jumps within 2.x and within 3.x; the only mandatory waypoints are 1.3 (for sources < 1.3) and 2.19 (for any 1.x/2.x → 3.x crossing). State the ACTUAL hops the customer needs (typically two: source → 2.19 → 3.x, or source → 2.19 if already 1.3+), not a fake per-minor chain.
If the response recommends migration steps inline (FULL_ASSESSMENT shape): name the migration tool / strategy by its proper name in §4 — Migration Assistant for Amazon OpenSearch Service Historical Data Migration, Snapshot/Restore, _reindex from remote, OSI, in-place blue/green, etc. Do NOT punt with "see the migration capability" or "follow assessment-workflow.md" — those references are for YOUR own routing, not for the user. The user receives a self-contained Migration Path section.
If the prompt named ≥3 simultaneous hard constraints (e.g., zero-downtime + zero-data-loss + no-third-party-tooling + EU residency, or any 3+ from the constraint-trilemma list in assessment-shape-comparative-decision.md § 2.5): the Executive Summary AND § 4 Migration Path MUST explicitly name the constraint conflict and recommend a relaxation. Phrasing template: "At <scale>, constraints {X, Y, Z} are mutually inconsistent without compromise. Recommend relaxing <constraint> by <quantified trade-off> — this converts the problem to <tractable shape> and Migration Assistant <strategy> applies cleanly." Do NOT silently claim a single tool path satisfies all named constraints simultaneously — the response will fail if it asserts an impossible feasibility. If the proposed path uses dual-write, also include the dual-write reconciliation rule ("application-layer dual-write authored by your team is customer code, not third-party tooling").

/amazon-opensearch-service

referencesassessment-shape-full-assessment.md