From 6221f3ff639c4211496a5fe91ae22d2573fcf39c Mon Sep 17 00:00:00 2001 From: Logan Kleier Date: Thu, 23 Jul 2026 16:03:53 -0700 Subject: [PATCH 1/3] feat(gcp-to-aws): journey orientation at start + answer recap before design MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - discover.md Step 0: on fresh runs, open with a 5-line orientation — six phases, user's part is small (confirm a sheet + 2-7 questions), what they get at the end, and that progress saves and resumes. Skipped on resume; never blocks — discovery continues in the same turn. - clarify.md Step 4: Answer Recap (GOV.UK 'check your answers' pattern) after the final essential batch — plays back question / user's words / recorded value for Step 4 answers only (sheet rows already confirmed). Informational when all answers were explicit option letters; waits for a response when any answer was interpreted from plain words, shorthand, or a skip. Corrections reuse the Step 2.5 override grammar. Applies to the full flow's final batch too; new validation checklist item. --- .../references/phases/clarify/clarify.md | 21 ++++++++++++++++++- .../references/phases/discover/discover.md | 6 ++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md index adf17484..a929ef04 100644 --- a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md +++ b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md @@ -476,9 +476,27 @@ _Present each question's options via the structured question tool (e.g. AskUserQ **Interpret answers** using the interpret rules in the category files. Apply early-exit rules triggered by answers (e.g., Q5 correction to multi-cloud → `compute: "eks"`, Q8 → N/A). +### 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 Step 4 only (sheet rows were already confirmed at Step 2.5 — do not repeat them): + +``` +### What I recorded — last check before design + +| Question | Your answer | Recorded as | +| -------- | ----------- | ----------- | +| Compliance (Q2) | "2A" | None | +| Cutover window (Q7) | "monthly is fine" | Monthly maintenance window | +| AI spend (Q15) | "about a grand" | $500–$2K/month | + +Anything wrong? Name it ("cutover: weekly") — otherwise I'll proceed to design. +``` + +**When to wait:** If every Step 4 answer was an explicit option letter, the recap is informational — append it to the same turn as the Category E opt-in (or the completion message) and proceed without requiring a reply. If **any** answer was interpreted from plain words, shorthand spanning multiple questions, or a skip, present the recap and **wait for the user's response** before Step 5 — interpretation is exactly where a misread silently becomes a design constraint. Corrections use the Step 2.5 override grammar and set `chosen_by: "user"`. + ### Full Flow variant ("ask me everything") -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 incl. Q11b Graviton + 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"`. +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 incl. Q11b Graviton + 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; skipped/defaulted ones summarized in one line, not per-row). ### Category E Opt-In @@ -803,6 +821,7 @@ Before handing off to Design: - [ ] In wizard mode, the Step 2.5 Assumption Sheet was shown (detected + assumed sections) and the user responded before any essential question was asked - [ ] 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:`) - [ ] 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" +- [ ] The Answer Recap was shown after the final Step 4 batch, and — when any answer was interpreted from plain words, multi-question shorthand, or a skip — the user responded to it before `preferences.json` was written - [ ] If `bigquery_present` was **true**, the Step 4 BigQuery specialist advisory was shown before questions — **or**, if Step 0 option A (reuse preferences), the same advisory was shown after BigQuery detection - [ ] `preferences.json` written to `$MIGRATION_DIR/` - [ ] `design_constraints.target_region` is populated with `value` and `chosen_by` diff --git a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/discover/discover.md b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/discover/discover.md index 334ecc6f..6c77d0fc 100644 --- a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/discover/discover.md +++ b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/discover/discover.md @@ -14,6 +14,12 @@ Multiple artifacts can be produced in a single run — they are not mutually exc ## Step 0: Initialize Migration State +0. **Orientation (fresh runs only):** When this is a new migration (no existing `.migration/` runs, or the user chooses Fresh below), open your first response with this block — before any scanning output. Skip it entirely when resuming an existing run (the breadcrumb in the resume message covers position). + + > **Here's how this works.** Six phases: I scan your Terraform, app code, or billing data; confirm a few assumptions with you; then design the AWS architecture, price it, and generate everything. Your part is small — most answers come from your own files; you'll typically confirm one summary sheet and answer 2–7 questions. At the end you get a migrate-or-stay recommendation with costs, ready-to-run Terraform, and step-by-step migration scripts. You can stop at any point — progress is saved and I'll resume where you left off. + + Do not pad it, restate it later, or block on it — continue directly into discovery in the same turn. + 1. Check for existing `.migration/` directory at the project root. - **If existing runs found:** List them with their phase status and ask: - `[A] Resume: Continue with [latest run]` From cf1cc84b3dbb1a267c1708b245f32a54857fb90c Mon Sep 17 00:00:00 2001 From: Logan Kleier Date: Thu, 23 Jul 2026 16:35:06 -0700 Subject: [PATCH 2/3] fix(gcp-to-aws): recap always waits, fixed sequencing, defaults included (review feedback) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drop the two-branch informational/wait rule: the batch opener invites shorthand and plain-word answers, so the informational branch almost never fired and a conditional rule is itself an interpretation hazard. The recap now always waits — one extra turn at the flow's highest-stakes commit. - Fixed sequence spelled out: recap -> wait -> Category E -> Step 5. - 'use defaults for the rest' now routes through the recap with defaulted rows shown as '(default applied)' — bulk defaults are the highest-risk interpretation and previously bypassed the recap entirely. - Orientation: 'ready-to-run Terraform' -> 'Terraform for the in-scope workloads' (BigQuery/specialist deferrals make the former an overpromise). --- .../references/phases/clarify/clarify.md | 16 ++++++++++++---- .../references/phases/discover/discover.md | 2 +- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md index a929ef04..e8a62cb2 100644 --- a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md +++ b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md @@ -472,7 +472,7 @@ _Present each question's options via the structured question tool (e.g. AskUserQ - Q3 defaults to B ($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 → E; Q23 → framework-based; Q24 → session; Q25 → medium; conflicts → most conservative posture) with `chosen_by: "default"`. - Then skip to Category E opt-in, then Step 5. + 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 the category files. Apply early-exit rules triggered by answers (e.g., Q5 correction to multi-cloud → `compute: "eks"`, Q8 → N/A). @@ -489,10 +489,18 @@ After the last essential batch is answered and interpreted (and after Q27 when i | Cutover window (Q7) | "monthly is fine" | Monthly maintenance window | | AI spend (Q15) | "about a grand" | $500–$2K/month | -Anything wrong? Name it ("cutover: weekly") — otherwise I'll proceed to design. +Anything wrong? Name it ("cutover: weekly") — or say "looks good" and I'll proceed to design. ``` -**When to wait:** If every Step 4 answer was an explicit option letter, the recap is informational — append it to the same turn as the Category E opt-in (or the completion message) and proceed without requiring a reply. If **any** answer was interpreted from plain words, shorthand spanning multiple questions, or a skip, present the recap and **wait for the user's response** before Step 5 — interpretation is exactly where a misread silently becomes a design constraint. Corrections use the Step 2.5 override grammar and set `chosen_by: "user"`. +**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 Step 2.5 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") @@ -821,7 +829,7 @@ Before handing off to Design: - [ ] In wizard mode, the Step 2.5 Assumption Sheet was shown (detected + assumed sections) and the user responded before any essential question was asked - [ ] 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:`) - [ ] 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" -- [ ] The Answer Recap was shown after the final Step 4 batch, and — when any answer was interpreted from plain words, multi-question shorthand, or a skip — the user responded to it before `preferences.json` was written +- [ ] The Answer Recap was shown after the final Step 4 batch (including defaulted rows on "use defaults for the rest") and the user responded to it before Category E / `preferences.json` - [ ] If `bigquery_present` was **true**, the Step 4 BigQuery specialist advisory was shown before questions — **or**, if Step 0 option A (reuse preferences), the same advisory was shown after BigQuery detection - [ ] `preferences.json` written to `$MIGRATION_DIR/` - [ ] `design_constraints.target_region` is populated with `value` and `chosen_by` diff --git a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/discover/discover.md b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/discover/discover.md index 6c77d0fc..2ceff7cc 100644 --- a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/discover/discover.md +++ b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/discover/discover.md @@ -16,7 +16,7 @@ Multiple artifacts can be produced in a single run — they are not mutually exc 0. **Orientation (fresh runs only):** When this is a new migration (no existing `.migration/` runs, or the user chooses Fresh below), open your first response with this block — before any scanning output. Skip it entirely when resuming an existing run (the breadcrumb in the resume message covers position). - > **Here's how this works.** Six phases: I scan your Terraform, app code, or billing data; confirm a few assumptions with you; then design the AWS architecture, price it, and generate everything. Your part is small — most answers come from your own files; you'll typically confirm one summary sheet and answer 2–7 questions. At the end you get a migrate-or-stay recommendation with costs, ready-to-run Terraform, and step-by-step migration scripts. You can stop at any point — progress is saved and I'll resume where you left off. + > **Here's how this works.** Six phases: I scan your Terraform, app code, or billing data; confirm a few assumptions with you; then design the AWS architecture, price it, and generate everything. Your part is small — most answers come from your own files; you'll typically confirm one summary sheet and answer 2–7 questions. At the end you get a migrate-or-stay recommendation with costs, Terraform for the in-scope workloads, and step-by-step migration scripts. You can stop at any point — progress is saved and I'll resume where you left off. Do not pad it, restate it later, or block on it — continue directly into discovery in the same turn. From bb3649376b2a17ae331dab882e5bb16bd1c5fd25 Mon Sep 17 00:00:00 2001 From: Logan Kleier Date: Thu, 13 Aug 2026 07:18:37 -0700 Subject: [PATCH 3/3] docs(gcp-to-aws): note why full-flow Answer Recap compresses defaults Make the wizard-vs-full-flow recap asymmetry explicit: answered questions stay per-row; skipped/defaulted collapse to one line so a long full-flow table stays scannable. Co-authored-by: Cursor --- .../skills/gcp-to-aws/references/phases/clarify/clarify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md index e8a62cb2..fc648c42 100644 --- a/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md +++ b/migrate/plugins/migration-to-aws/skills/gcp-to-aws/references/phases/clarify/clarify.md @@ -504,7 +504,7 @@ Anything wrong? Name it ("cutover: weekly") — or say "looks good" and I'll pro ### Full Flow variant ("ask me everything") -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 incl. Q11b Graviton + 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; skipped/defaulted ones summarized in one line, not per-row). +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 incl. Q11b Graviton + 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