Clarify AI Only

Input contract. The only profile this flow reads is the provider-neutral ai-workload-profile.json (schema_version, ai_sources[], gateways[]), already accepted by scripts/validate-ai-profile.py. Use that script’s JSON summary for every detected value below. A 1.1 profile also carries integration; from it the summary reports ai_framework_detected and ai_vision_detected. Both are null for a 1.0 profile or when the evidence is not definitive, and then Q1 and Q6 are asked, not extracted. Do not scan application code or IaC, and do not read usage-profile files or any other file: only the validator summary can supply an extracted answer.

Produces the same preferences.json output but with design_constraints limited to region and compliance, startup_constraints populated, and ai_constraints fully populated. Questions are presented in two progressive batches with an intermediate save — partial answers persist across sessions.

Step 0: Prior Run Check

Check $MIGRATION_DIR/ for existing state:

Case 1 — Completed preferences exist (preferences.json present):

“I found existing migration preferences from a previous run. Would you like to:”

1. Re-use these preferences and skip questions
2. Start fresh and re-answer all questions

• If 1: delete preferences-draft.json if it exists, then skip to Step 4 with the existing preferences.json.
• If 2: delete preferences.json and preferences-draft.json (if present), continue to Step 1.

Case 2 — Draft preferences exist (preferences-draft.json present, no preferences.json):

“I found a partial set of answers from a previous session (1 of 2 batches completed). Would you like to:”

1. Resume from where you left off — I’ll pick up the remaining questions
2. Start fresh and re-answer all questions

• If 1: load the draft, skip Batch 1 in Step 2, present Batch 2 directly.
• If 2: delete preferences-draft.json, continue to Step 1.

Case 3 — No prior state: Continue to Step 1.

Step 1: Present AI Detection Summary

AI-Only Migration Detected This release migrates AI calls only. Infrastructure stays where it runs.

AI sources: [one line per ai_sources[] entry: provider via source_service, plus “through [gateway product]” for each name in via_gateways] Models detected: [each source’s models[].model, with raw_model when it differs; “not observed” when model_evidence is not_observed] Gateway/router: [each gateways[].product with “upstreams unresolved” when upstream_evidence is unresolved, or “None (direct SDK)”]

Step 1.5: Fast-Path Check

The fast path is gated on migration-preview.json, which this skill does not produce yet. Continue to Step 1.75 (mini assumption sheet), then Step 2.

Step 1.75: Mini Assumption Sheet (before Batch 1)

Before asking anything, present what the profile already answered as a compact confirm-or-edit sheet (sheet first, questions after the user responds). If the sheet has no rows, skip this step:

Questions resolved on this sheet are not re-asked in the batches below; record them with chosen_by: "extracted" and skip their entries in Batch 1/2. Rows the user corrects become chosen_by: "user". The sheet never assumes a value: every question without a detected row stays in the batches, and only “use defaults for the rest” applies defaults.

Show the Models row under “Detected” only when the validator summary reports models_extractable: true, and list every observed model. If it is false, leave the row out of the sheet and ask Q5 in Batch 1 with the detected models as the suggested answer; a user who confirms them records chosen_by: "user". Show Framework only when ai_framework_detected is not null, and Input types only when ai_vision_detected is not null.

Step 2: Ask Questions in Progressive Batches (Q1–Q11, incl. Q1.5)

Questions are presented in two batches with a save after the first. The user can skip individual questions (defaults applied), say “use defaults for the rest” to apply defaults for all remaining questions and proceed immediately, or answer normally.

Batch 1 — AI Strategy & Setup (Q1–Q5 + Q1.5)

Present with this intro:

Q1 — AI framework or orchestration layer (select all that apply)

Skip when: the validator summary reports a non-null ai_framework_detected. Record that list with chosen_by: "extracted" and source: "ai-profile:integration", and do not present this question. Otherwise, when the summary lists a gateway, present the confirm card below with option 2 as the detected value and the gateway product as the evidence. Otherwise present the full question.

Gateway confirm card:

Your AI profile shows calls through [gateway product, e.g. openrouter].

1. That’s right — the gateway is how our app reaches the models
2. Edit — show me all framework options
3. Gateway plus a framework — show me all framework options with the gateway selected

Accept → record ["llm_router"] with chosen_by: "user". Edit or option 3 → fall through to the full question below, with option 2 preselected for option 3.

1) No framework — direct API calls | 2) LLM router/gateway | 3) LangChain / LangGraph | 4) Multi-agent framework | 5) OpenAI Agents SDK | 6) MCP/A2A | 7) Voice platform

Never recommend classic Bedrock Agents (bedrock-agent) as a migration target. It is in maintenance mode and closed to new customers as of July 30, 2026 (AWS announcement (opens in a new tab)). Agentic targets are AgentCore Harness (config-based, default) or AgentCore Runtime (code-defined loops).

Combination Logic

If answer includes 2 and no other selections, skip or abbreviate SDK migration steps. If answer is 1 only, proceed with standard model migration flow.

Interpret → ai_framework array. Default: auto-detect, fallback ["direct"].

Q1.5 — Do you have any compliance or regulatory requirements? (select all that apply)

Compliance gates Bedrock regions, models, and logging even though your infrastructure stays where it is — customer data flows to AWS the moment model calls do. The impacts below are the Bedrock-specific subset that applies on this path.

Even with infrastructure staying where it is, your prompts and completions will be processed on AWS. Compliance requirements determine which Bedrock regions, models, and configurations are available.

1) None | 2) SOC 2 / ISO 27001 | 3) PCI DSS | 4) HIPAA | 5) FedRAMP / Government | 6) GDPR / Data residency | 7) CCPA / CPRA | 8) I don’t know

(Multiple selections allowed)

Interpret → design_constraints.compliance array (same format as the full flow). An explicit user answer of 1 records ["none"] with chosen_by: "user". Skip/default records ["unknown"] (never a silent “none” — full-flow Q2 semantics: behaves like “none” for service selection) with chosen_by: "default", source: "default:Q1.5" — and append the caveat “Compliance requirements were not confirmed by the user” to metadata.report_caveats[] (create the array if absent) so downstream reports surface it. Cross-check with Q4: a GDPR answer constrains the target region jointly with cross-cloud latency.

Q2 — What matters most for your AI application?

1) Best quality/reasoning | 2) Fastest speed | 3) Lowest cost | 4) Specialized capability (→ Q10) | 5) Balanced | 6) I don’t know

Interpret → ai_priority. Default: 5 → "balanced".

Q3 — Monthly AI spend on OpenAI or Gemini?

1) < $500 | 2) $500–$2K | 3) $2K–$10K | 4) > $10K | 5) Don’t know

Interpret → ai_monthly_spend. Default: 2 → "$500-$2K".

Q4 — Cross-cloud API call concerns

Unique to AI-only: infrastructure stays with its current provider while AI calls route to AWS.

1) Latency critical — AI in hot path | 2) Latency acceptable — async/users can wait | 3) Concerned about egress costs | 4) Want to test first — parallel running

Interpret → cross_cloud. Default: 2 → "latency-acceptable".

Q5 — Current model in use?

Establishes baseline Bedrock recommendation. Override hierarchy: Q10 special features > Q2 priority > Q7/Q8 volume/latency > Q5 baseline.

Skip when: the validator summary reports models_extractable: true — every source has model_evidence: "observed" and every observed model has at least one confidence: "high" evidence entry (user-confirmed evidence is always high) — auto-detect with chosen_by: "extracted", source: "ai-profile:ai_sources[].models", and do not present this question. The detected models are already shown in the Step 1 summary. Otherwise, present the question with the detected model(s) offered as the suggested answer. With 2+ detected models, record ai_model_baseline as an array (one entry per model).

1) Gemini Flash | 2) Gemini Pro | 3) GPT-3.5 Turbo | 4) GPT-4/4 Turbo | 5) GPT-4o | 6) GPT-5.4/Mini/Nano | 7) GPT-5.6 Sol/Terra/Luna | 8) GPT-5/5.x (older) | 9) GPT-5.5/Pro | 10) GPT-6/6.1 (Astra/Sol/Luna) | 11) o-series | 12) Claude (Anthropic SDK) | 13) Other/Multiple | 14) Don’t know

Same-model rows first. GPT-6 Astra / GPT-5.6 / 5.5 / 5.4 sources map to themselves. Design applies the model-specific API and region gate; Clarify records the baseline only. Astra Standard mantle supports us-east-1 and us-west-2; runtime uses US Geo / Global CRIS. GPT-5.6 also has runtime CRIS; GPT-5.5 / 5.4 remain mantle-only. GPT-5.x in-region costs about 10% above OpenAI standard, while GPT-5.6 Global CRIS uses the standard rate. For Astra, compare its separately dated inference/context tier against the source price before claiming savings or parity. For sources without a Bedrock equivalent, present a same-vendor upgrade and a cross-family option.

Override examples: GPT-4 + Q2=cost → Haiku; Flash + Q10=extended thinking → Sonnet; GPT-4o + Q10=speech → Nova 2 Sonic; GPT-5.5 + Q2=cost → Sonnet 5.

Interpret → ai_model_baseline. Default: auto-detect, fallback Q2 priority-based.

Batch 1 → Save Draft and Present Batch 2

After the user responds to Batch 1:

1. Interpret all Batch 1 answers (apply interpret rules above; apply defaults for skipped questions).
2. Write $MIGRATION_DIR/preferences-draft.json with Batch 1 answers:

1. Present Batch 2:

“Use defaults for the rest” handling: If the user says this during Batch 1, apply defaults for all unanswered Batch 1 questions and all Batch 2 questions, then skip directly to Step 3. Skip the Batch 1 draft save on this path — assembly happens in the same turn, so a draft would serve no crash-recovery purpose.

Batch 2 — Technical Requirements (Q6–Q11)

Q6 — What input types must the model accept: text only, images (vision), or audio/video?

Skip when: the validator summary reports a non-null ai_vision_detected. Record it with chosen_by: "extracted" and source: "ai-profile:integration.capabilities_summary", and do not present this question. Otherwise ask.

1) Text only | 2) Vision required | 3) Audio/Video inputs

Interpret → ai_vision: 1 → "text-only", 2 → "vision", 3 → "audio". Default: 1 → "text-only" (no constraint).

Q7 — Monthly AI usage volume

Never skipped: do not fill this from a usage-profile file or from the assumption sheet. Ask it unless the user says “use defaults for the rest”.

1) < 1M tokens | 2) 1–10M | 3) 10–100M | 4) > 100M | 5) Don’t know

Interpret → ai_token_volume: 1 → "low", 2 → "medium", 3 → "high", 4 → "very_high". Default: 2 → "medium".

Q8 — Response speed importance

Present with concrete anchors: Critical = autocomplete/live chat; Important = chat assistant; Flexible = reports/batch.

1) Critical (< 500ms) | 2) Important (< 2s) | 3) Flexible (2–10s)

Interpret → ai_latency. Default: 2 → "important".

Q9 — AI task complexity

Present with concrete examples: Simple = classify/extract/summarize; Moderate = analyze+JSON/few-shot; Complex = multi-turn reasoning/tool use/agentic.

1) Simple | 2) Moderate | 3) Complex

Interpret → ai_complexity. Default: 2 → "moderate".

Q10 — Specialized features needed

1) Function calling | 2) Ultra-long context (> 300K) | 3) Extended thinking | 4) Prompt caching | 5) RAG optimization | 6) Agentic workflows | 7) Real-time speed | 8) Image generation | 9) Conversational speech | 10) None

Interpret → ai_critical_feature. Default: 10 → no override.

Q11 — Have you applied for AWS Activate credits?

Activate eligibility: Pre-Series B, founded in the last 10 years, AWS Account on Paid Tier Plan, and either new to Activate Credits or requesting more credits than previously received. AI-only migrations are exactly the workloads Activate credits offset — Bedrock usage (Claude, Llama, Nova) is credit-eligible. Never infer funding stage or Activate tier from Q3 spend.

AWS Activate credits offset Bedrock costs during and after migration — including Claude, Llama, and Nova models. Eligible startups can get $5K–$200K depending on funding stage.

1. Yes — already have AWS Activate credits
2. No — haven’t applied yet (self-funded or pre-VC)
3. No — VC/accelerator-backed but haven’t applied
4. I don’t know

Escalations (adapted to AI-only signals): if ai_monthly_spend is ">$10K", also flag AWS Credits for AI Startups ($200,000+, invite-only — contact your AWS Account Manager). If ai_monthly_spend is "$2K-$10K" or ">$10K" AND the workload is agentic (Q1 includes 4/5/6 or Q10 = 6), also flag AWS Generative AI Accelerator (up to $1M credits, 8-week cohort): aws.amazon.com/startups/generative-ai/accelerator

Interpret → startup_program_status: 1 → "has_credits", 2 → "eligible_founders", 3 → "eligible_portfolio", 4 → "unknown". Default: 4 → "unknown" — downstream artifacts must use neutral Activate copy (both tiers, no “your status: eligible_*”).

Batch 2 Complete

After the user responds to Batch 2, interpret all Batch 2 answers and proceed to Step 3.

Step 3: Assemble and Write preferences.json

Assemble all interpreted answers from both batches into the final file. If preferences-draft.json exists and was resumed in Step 0 Case 2, use it as the base — merge in Batch 2 answers, remove draft-specific metadata fields (draft, batches_completed, batches_remaining), and set metadata.timestamp to the current time.

Write $MIGRATION_DIR/preferences.json:

Schema — AI-only structure:

ai_capabilities_required is omitted: Q6 and Q10 already record the requirement.

Each constraint carries the FULL field shape in references/shared/schema-preferences.md — value, chosen_by (user|extracted|default|derived), prompt, design_consequence, and source/question_id per that file’s source-field rules. (The short { value, chosen_by } form shown above is an abbreviation, not the schema.) No nulls. All rules in that file apply, with two AI-only bindings: metadata.clarify_mode is "fast_path" when Step 1.5 fired, "full" for the two-batch flow; and this flow’s questions_extracted is the full flow’s questions_skipped_extracted (downstream consumers accept both names).

After writing preferences.json, delete $MIGRATION_DIR/preferences-draft.json if it exists.

Step 4: Update Phase Status

Before phase completion, enforce output gate:

• preferences.json must exist.
• preferences.json.metadata.migration_type must equal "ai-only".

If either check fails: STOP and output: “AI-only clarify output validation failed. Fix preferences.json before completing Clarify.”

Use read-merge-write (as described in SKILL.md) to update .phase-status.json in the same turn as the output message:

• Set phases.clarify to "completed"
• Set current_phase to "complete"

Output: “Clarification complete. Your answers are saved in preferences.json.” Then stop: this skill does not yet include Design, Estimate, or Generate.