Clarify Assemble

Schema reference: references/shared/schema-preferences.md.

This unit owns the conversation

Fragments compute rows. The assembler is the only thing that talks to the user, and it runs three gates in order, plus the two GCP-specific mechanisms (fast paths, Full Flow opt-out) that live in clarify.md and short-circuit before reaching this file. See clarify.md § Step 2 for why presentation is centralised here.

Step 2 (extraction detail): BigQuery / Deferred Analytics

One extraction step does not belong to any single fragment because it gates a report callout, not a design constraint:

BigQuery / analytics warehouse — Set bigquery_present to true if any of: (a) a resource in gcp-resource-inventory.json has gcp_type (or equivalent type field) starting with google_bigquery_; (b) billing-profile.json lists a service/SKU that clearly indicates BigQuery (e.g., service name or SKU contains BigQuery). Otherwise bigquery_present is false. Record in metadata.inventory_clarifications.bigquery_present.

Gate 1 — The Assumption Sheet (Mandatory Gate)

When to run: Always in wizard mode, after all triggered fragments return their rows — whenever at least one row is DETECTED or PROPOSED.

Skip Gate 1 only when every active row is ESSENTIAL or N/A (rare — e.g., empty discovery with Category A only). Proceed directly to Gate 2.

HARD GATE — do NOT ask any essential question until the user responds to this sheet.

Present the sheet in two sections (omit rows for questions that are ESSENTIAL or N/A). Keep each consequence to one line — use the consequence text supplied by each row’s fragment:

Present these as selectable options via the structured question tool (e.g. AskUserQuestion) when the IDE provides one; otherwise show the numbered list above verbatim. Free-text corrections are always accepted in either mode — the menu supplements the override grammar, it never replaces it.

Computing [N]: Count ESSENTIAL dispositions across all triggered fragments, plus any rows converted to ESSENTIAL via user correction (“ask me about X”), plus conflict rows. Subtract any ESSENTIAL questions that were already answered by a user correction on the sheet (e.g., user said "availability: mission-critical" — the availability question no longer needs asking).

Multi-instance Cloud SQL conflicts: When instances disagree, replace the single-row summary with a per-instance table and keep the conflicting question ESSENTIAL until resolved:

Override handling — when the user corrects a value (detected or assumed):

For each override: set chosen_by: "user" on the constraint (this removes the source field since it’s no longer extracted/default). For extracted rows, also remove the question ID from metadata.questions_skipped_extracted; for assumed rows, remove it from metadata.questions_defaulted.

When the user confirms (“looks good”): no further action needed — the constraint objects already carry their chosen_by and source fields.

“Ask me everything”: clear questions_skipped_extracted and questions_defaulted; set all previously extracted/assumed constraints to pending; set metadata.clarify_mode: "full" and run the Full Flow variant (below) instead of Gate 2.

Constraint source field: When writing a constraint with chosen_by: "extracted" or chosen_by: "default", include the source field on the constraint object itself:

• Extracted: raw provenance signal (e.g. "terraform:availability_type=ZONAL", "billing:region=us-west1", "ai-profile:integration.pattern=direct_sdk")
• Default: "default:<Qid>" (e.g. "default:Q16")

Omit source when chosen_by is "user" or "derived".

After the user responds, write preferences-draft.json with all resolved values and metadata.wizard_stage: "essentials_pending", then proceed to Gate 2.

Category E — Migration Posture (Disabled by Default)

Fire when: User explicitly opts in. Default behavior when disabled: Apply conservative defaults — no HA upgrades, no right-sizing.

Superseded by clarify-global.md‘s cost-optimization-appetite row for the right-sizing half: per references/vendored/clarify/clarify-cost-appetite.md § “What a consuming skill supplies” item 1, a run that resolved that row to aggressive should behave as if it opted into right_sizing: true here without asking Q-E2 separately. Q-E1 (HA upgrade opt-in) remains a distinct opt-in.

If the user opts in, present after the essentials:

Q-E1 — Should we recommend upgrading Single-AZ to Multi-AZ where possible?

1) Yes — upgrade to Multi-AZ for higher availability | 2) No — keep current topology

Interpret → ha_upgrade: 1 → true, 2 → false. Default: 2 → false.

Q-E2 — Should we use billing utilization data to right-size instance types?

Skip when the cost-optimization-appetite row already resolved to aggressive — apply right_sizing: true directly per the supersession rule above instead of asking.

1) Yes — right-size based on utilization | 2) No — match current capacity

Interpret → right_sizing: 1 → true, 2 → false. Default: 2 → false.

Gate 2 — The Essential Questions

Prerequisite: Gate 1 sheet confirmation must be complete (user said “looks good” or finished correcting) before asking anything. Do not re-show the full sheet here unless the user asks for a recap.

COMPLIANCE SELF-CHECK (do this before emitting any question): Verify both: (1) the Assumption Sheet was presented in a previous turn, and (2) the user has responded to it. If either is false, STOP — present the sheet and wait. Never combine the sheet and essential questions in a single message, and never ask a question that has a sheet row unless the user converted it via a correction or “ask me about X”.

BigQuery / deferred analytics (mandatory callout): If bigquery_present is true, output this block once, before any questions (same turn as the essentials), then continue:

BigQuery / analytics warehouse: Your discovery inputs include BigQuery. This skill does not select an AWS analytics or data-warehouse target (no Athena, Redshift, Glue, or EMR recommendation from the plugin). Before warehouse, data lake, SQL analytics, or BI cutover planning, engage your AWS account team and/or a data analytics migration partner to assess query patterns, data volumes, ETL/ELT, and downstream consumers. Design will mark these resources as Deferred — specialist engagement.

Essentials Batches

Present the essential questions (from each fragment’s disposition, plus any rows converted by “ask me about X”) in batches of at most 4 per turn, numbered from 1, with the question text, context, and options from the fragment files. Typical total: 2–7.

Batch composition: core first (Q1/Q2/Q3/Q3.5/Q7 + conflicts, from clarify-global.md), then AI/agentic (Q15, Q23–Q25, multi-workload confirmations, from clarify-ai.md). Q27 is not batched — ask it as its own short follow-up after the last batch, per the presentation rule in clarify-ai.md Q27 (it’s a funding question, not a technical one). Write preferences-draft.json between batches (same schema as preferences.json plus metadata.wizard_stage). When more than one batch is needed, open each with a progress line: “Batch [i] of [k].”

Open the first batch with:

Present each question’s options via the structured question tool (e.g. AskUserQuestion) when the IDE provides one — one tool call per batch, identical option text. Otherwise use the lettered options in chat as shown. Shorthand and plain-word answers are accepted in either mode.

This ≤4 cap applies to wizard essentials only. The Full Flow variant below keeps its documented three-batch structure — the user explicitly opted into the long path and has shorthand answering.

Wait for the user’s response. Do NOT proceed to Design without a response or an explicit “use defaults for the rest.”

“Use defaults for the rest” handling: Apply documented defaults for all unanswered essential questions except those marked “never assumed” in each fragment when a safe default genuinely does not exist:

• Q2 (compliance) defaults to unknown — write compliance: {value: ["unknown"], chosen_by: "default", source: "default:Q2"}. Never record silent “no requirements”; ["unknown"] behaves like “none” for service selection but triggers the report compliance caveat. See references/vendored/clarify/clarify-compliance.md.
• Q7 defaults to 4 (flexible).
• Q3 defaults to 2 ($1K–$5K) with a report caveat that spend was not confirmed.
• Q27 must not be silently defaulted in wizard mode when Category H fired — if the user skips it, record startup_program_status: "unknown" with chosen_by: "default" and source: "default:Q27"; downstream artifacts must use neutral Activate copy (both tiers, no “your status: eligible_*”).
• Q3.5, Q23–Q25, and unresolved multi-instance conflicts fall back to their documented defaults (Q3.5 → 5; Q23 → framework-based; Q24 → session; Q25 → medium; conflicts → most conservative posture) with chosen_by: "default". Then run the Answer Recap (below) with the defaulted rows included, then Category E opt-in, then Step 5.

Interpret answers using the interpret rules in each fragment file. Apply early-exit rules triggered by answers (e.g., the multi-cloud row’s correction to “yes” → compute: "eks", Q8 → N/A).

Gate 3 — The Answer Recap (Check Your Answers)

After the last essential batch is answered and interpreted (and after Q27 when it fired), play back what was recorded — the essentials are the only answers in the flow the user states rather than confirms, and shorthand (“1A 2C”) plus plain-word answers pass through an interpretation step the user never sees. One compact table, questions asked in Gate 2 only (sheet rows were already confirmed at Gate 1 — do not repeat them):

Always wait. Present the recap and wait for the user’s response (“looks good” or a correction) before continuing — interpretation is exactly where a misread silently becomes a design constraint, and the batch opener invites shorthand and plain-word answers, so nearly every real run involves interpretation. One extra turn at the single highest-stakes commit in the flow is the intended cost. Corrections use the Gate 1 override grammar and set chosen_by: "user".

Sequence (fixed — do not reorder or combine):

1. Answer Recap → wait for the user’s response
2. Category E opt-in (if billing-profile.json exists) → wait
3. Step 5 — write preferences.json

“Use defaults for the rest” still gets a recap: when the user defaults remaining questions, include those rows with (default applied) in the “Your answer” column and the defaulted value in “Recorded as” — bulk-defaulting is the highest-risk interpretation of all, and this is the user’s one chance to see what “the rest” actually meant. Then wait as above.

Full Flow variant (“ask me everything”)

GCP-specific — azure-to-aws has no equivalent opt-out flow. When the user opted out of the wizard, run the progressive-batch flow: present ALL active questions (no dispositions) in up to three batches — Strategic (Q1–Q7, minus Q4), Infrastructure (Q8–Q13b including Q11b Graviton and Category B), AI (Q14–Q27, Q23–Q26 only if agentic) — writing preferences-draft.json between batches with metadata.batches_completed / metadata.batches_remaining (values: "strategic", "infrastructure", "ai"). Per-question skip and “use defaults for the rest” behave as documented. Set metadata.clarify_mode: "full". The Answer Recap above runs after the final batch here too (all answered questions as rows; skipped/defaulted ones summarized in one line, not per-row — intentional compression so a 20+ question full-flow recap stays scannable; the wizard already shows every defaulted essential as a (default applied) row because that set is small. Do not silently drop answered questions into the one-liner).

Category E Opt-In

After the essentials are answered (but before writing final preferences.json), offer Category E if billing-profile.json exists:

“Would you also like HA upgrade and right-sizing recommendations based on your billing data? If not, I’ll use conservative defaults (no upgrades, match current capacity).”

If user opts in, present Q-E1, and Q-E2 unless the cost-optimization-appetite row already resolved to aggressive (then apply right_sizing: true without asking Q-E2). Otherwise, apply Category E defaults (ha_upgrade: false, right_sizing: false).

Answer Combination Triggers

Step 5: Assemble and Write preferences.json

Assemble all resolved values — sheet confirmations, corrections, essential answers, and defaults — into the final $MIGRATION_DIR/preferences.json. Every constraint object MUST include prompt and design_consequence per references/shared/schema-preferences.md (use the constraint catalog when the user did not see the verbatim question).

If preferences-draft.json exists, use it as the base — merge in the final answers, remove the draft-specific metadata fields (draft, wizard_stage, batches_completed, batches_remaining), and set metadata.timestamp to the current time. Write $MIGRATION_DIR/preferences.json:

Schema Rules

Full schema and constraint catalog: references/shared/schema-preferences.md.

1. Every entry in design_constraints, ai_constraints, and startup_constraints (when present) is an object with value, chosen_by, prompt, and design_consequence fields. Optional question_id when mapped to the Q1–Q27 catalog. Optional source when chosen_by is "extracted" or "default".
2. prompt: verbatim question from the fragment file when chosen_by is "user"; detection label when "extracted"; question + " (default applied)" when "default"; derivation label when "derived".
3. design_consequence: one sentence from the fragment’s Recommendation Impact for the selected answer, or the catalog template in schema-preferences.md with [value] substituted.
4. chosen_by values: "user" (explicitly answered or corrected on the sheet), "default" (documented default applied — includes sheet-confirmed defaults and “I don’t know” answers), "extracted" (inferred from inventory), "derived" (computed from combination of answers + detected capabilities).
5. source field on constraints: Every constraint with chosen_by: "extracted" or chosen_by: "default" MUST include a source field. Extracted: raw provenance signal (prefix terraform:, billing:, code:, inventory:, ai-profile:, or artifact filename). Default: "default:<Qid>". Omit source for "user" and "derived". Report generation uses source prefixed default: to flag unverified assumptions.
6. Only write a key to design_constraints / ai_constraints if the answer produces a constraint. Absent keys mean “no constraint — Design decides.”
7. Do not write null values. Do not omit prompt or design_consequence on any written constraint.
8. For billing-source inventories, metadata.inventory_clarifications records Category B answers.
9. metadata.questions_skipped_early_exit records questions skipped due to early-exit logic (e.g., Q8 skipped because the multi-cloud row resolved to “yes”).
10. metadata.questions_skipped_extracted records questions resolved because inventory already provided the answer.
11. metadata.questions_defaulted records questions resolved by documented default — whether sheet-confirmed (wizard) or skipped (full flow / “use defaults”).
12. metadata.questions_skipped_not_applicable records questions skipped because the relevant service wasn’t in the inventory or their firing condition wasn’t met.
13. ai_constraints section is present ONLY if Category F fired. Omit entirely if no AI artifacts exist.
14. ai_constraints.ai_capabilities_required is the UNION of detected capabilities from ai-workload-profile.json + critical feature from Q17 + vision from Q20. chosen_by is "derived".
15. ai_constraints.ai_framework is an array (Q14 is select-all-that-apply). If auto-detected, chosen_by is "extracted" with source.
16. metadata.clarify_mode is one of "wizard", "full", "fast_path", "simple_hybrid".

After writing preferences.json, delete $MIGRATION_DIR/preferences-draft.json and $MIGRATION_DIR/preferences-superseded.json if they exist (the superseded backup has served its purpose once a new complete file exists).

Defaults Table

Documented defaults for every question. Used by: PROPOSED sheet rows (wizard), per-question skips, “use defaults for the rest”, and the fast paths.

Validation Checklist

Before handing off to Design:

• Not done: In wizard mode, the Gate 1 Assumption Sheet was shown (detected + assumed sections) and the user responded before any essential question was asked
• Not done: Every constraint with chosen_by: "extracted" or chosen_by: "default" has a source field with the correct prefix (terraform:, billing:, inventory:, ai-profile:, or default:<Qid>)
• Not done: Essential questions (Q2, Q7, and conditional Q1/Q3/Q3.5/Q27/Q15/Q23–Q25/conflicts) were asked, answered, or explicitly defaulted via "use defaults for the rest"
• Not done: The Answer Recap was shown after the final Gate 2 batch (including defaulted rows on “use defaults for the rest”) and the user responded to it before Category E / preferences.json
• Not done: If bigquery_present was true, the mandatory BigQuery specialist advisory was shown before questions — or, if clarify.md Step 0 option 1 (reuse preferences), the same advisory was shown after BigQuery detection
• Not done: preferences.json written to $MIGRATION_DIR/
• Not done: design_constraints.target_region is populated with value and chosen_by
• Not done: design_constraints.compliance is populated (never silently absent — the compliance question always fires per references/vendored/clarify/clarify-compliance.md)
• Not done: design_constraints.availability is populated when Cloud SQL PostgreSQL/MySQL is in inventory (asked, extracted, or defaulted — Design must not run with absent/null availability)
• Not done: If compute resources are present, design_constraints.cpu_architecture is set to graviton, x86, or mixed per the Q11b decision table
• Not done: Only keys with non-null values are present in design_constraints
• Not done: Every entry in design_constraints and ai_constraints has value and chosen_by fields
• Not done: Config gap answers recorded in metadata.inventory_clarifications (billing mode only)
• Not done: Early-exit skips recorded in metadata.questions_skipped_early_exit
• Not done: ai_constraints section present ONLY if Category F fired
• Not done: If Category F fired, ai_constraints.ai_framework is populated (from detection or Q14)
• Not done: If Category F fired, ai_capabilities_required is derived from detection + Q17 + Q20
• Not done: ai_constraints.ai_framework is an array (Q14 is multi-select)
• Not done: Output is valid JSON
• Not done: preferences-draft.json has been deleted (if it existed)
• Not done: metadata.clarify_mode is set to "wizard", "full", "fast_path", or "simple_hybrid"

Completion Handoff Gate (Fail Closed)

Load shared/handoff-gates.md. Re-read from disk before checking.

Re-entry guard: If aws-design.json (or aws-design-ai.json / aws-design-billing.json) exists and phases.design is "completed": STOP unless the user explicitly confirms re-running Clarify. Emit GATE_FAIL | phase=clarify | field=aws-design.json | reason=stale_downstream.

Checks (all must PASS):

1. preferences.json exists and parses as JSON.
2. Validation Checklist items above all pass (including metadata.clarify_mode).
3. If gcp-resource-inventory.json contains google_sql_database_instance → design_constraints.availability.value is set (non-null, non-empty).
4. If metadata.clarify_mode is "wizard" → at least one constraint has a source field OR every active question was essential.
5. No sheet/question mixing: metadata.questions_asked contains no question ID that also appears in metadata.questions_skipped_extracted or metadata.questions_defaulted. (A question may move between lists only if the user converted its sheet row — in which case the override handling moved it to questions_asked.)
6. If compute resources are present (Cloud Run, Cloud Functions, GKE, GCE in gcp-resource-inventory.json, or billing-source compute) → design_constraints .cpu_architecture.value is set (graviton | x86 | mixed), per the Q11b decision table in clarify-compute.md — written even when Q11b was auto-defaulted.
7. Extraction consistency — Q13b (skip this check when metadata.clarify_mode is "full" — the user explicitly opted into the full question flow): If every google_sql_database_instance in gcp-resource-inventory.json carries an unambiguous disk size (config.disk_size_gb or legacy variants, all mapping to the same Q13b band) → Q13b must NOT appear in metadata.questions_asked unless design_constraints.db_size .chosen_by is "user" (the user converted the sheet row via “ask me about X” or corrected it). If instances map to different bands (e.g. an 8 GB dev instance and a 200 GB prod instance), the size is ambiguous — this check does NOT fire, and asking Q13b is the expected behavior (matching the clarify-database.md auto-detect rule “if multiple instances disagree, ask Q13b”). Otherwise: GATE_FAIL | phase=clarify | field=metadata.questions_asked | reason=extractable_question_asked_Q13b.
8. Extraction consistency — Q19 (skip when metadata.clarify_mode is "full"): If ai-workload-profile.json exists with models[0].model_id set at confidence ≥ 0.8 → Q19 must NOT appear in metadata.questions_asked unless ai_constraints .ai_model_baseline.chosen_by is "user". Otherwise: GATE_FAIL | phase=clarify | field=metadata.questions_asked | reason=extractable_question_asked_Q19. (Detect-confirm cards for sub-threshold or tied detection per clarify-ai.md are not affected — they fire only when confidence < 0.8.)

On any FAIL: Emit GATE_FAIL | phase=clarify | field=<path> | reason=missing. Do NOT modify artifacts to pass the gate. Do NOT update .phase-status.json. Tell the user to answer the missing question or re-run Clarify.

On PASS: Emit HANDOFF_OK | phase=clarify | artifacts=preferences.json.

Step 6: Update Phase Status

Only after HANDOFF_OK. In the same turn as the output message below, use the Phase Status Update Protocol (Write tool) to write .phase-status.json with phases.clarify set to "completed".

Output to user: “Phase 2 of 6 complete (Clarify). Remaining: Design → Estimate → Generate (+ optional Feedback). Next artifact: aws-design.json. Proceeding to Phase 3: Design AWS Architecture.”

Breadcrumbs are emitted only after outer-run HANDOFF_OK — never on GATE_FAIL, never from inner workshop reprices.

Scope Boundary

This phase covers requirements gathering ONLY.

FORBIDDEN — Do NOT include ANY of:

• Detailed AWS architecture or service configurations
• Code migration examples or SDK snippets
• Detailed cost calculations
• Migration timelines or execution plans
• Terraform generation

Your ONLY job: Understand what the user needs. Nothing else.

Status — build step 5 (restructure)

Implemented. This file absorbs everything the prior monolithic clarify.md did after extraction — the Assumption Sheet, the essential-questions batching, the Answer Recap, Category E, the Full Flow variant, the preferences.json write, the Defaults Table, the Validation Checklist, and the Completion Handoff Gate — matching the responsibility split azure-to-aws‘s clarify-assemble.md already has, adapted to GCP’s larger built-in structure (fast paths, Full Flow opt-out, Category E) that Azure’s assembler does not need. No firing rule, default, or interpretation rule changed in this move.