feat(gcp-to-aws): journey orientation at start + answer recap before design

[herosjourney]

Summary

The problem, in plain English: The flow is missing the first and last lines of a well-designed form. At the front: a founder who types "migrate my GCP stack" gets state-directory mechanics and then questions — never "here's what this is, how little of your time it takes, what you get at the end, and that you can stop and resume anytime." A founder who doesn't know resume exists treats any interruption as starting over. At the back: the essential questions are the only answers in the whole flow the user states rather than confirms — and they arrive as shorthand ("1A 2C 3 skip") and plain words ("about a grand") that the agent interprets. That interpretation step is exactly where an agent misreads, and it's the one step with zero user visibility: a misheard "2C" flows silently into Design, Estimate, and generated Terraform.

Changes:

• Journey orientation (discover.md Step 0): fresh runs open with a five-line block — six phases, your part is small (most answers come from your own files; confirm one sheet, answer 2–7 questions), what you get at the end (migrate-or-stay recommendation with costs, Terraform for the in-scope workloads, migration scripts), and that progress saves and resumes. Skipped on resume (the fix(gcp-to-aws): discover-preview display contradiction + phase progress breadcrumbs #169 breadcrumbs cover position there); explicitly non-blocking — discovery continues in the same turn.
• Answer Recap (clarify.md Step 4, new subsection): after the final essential batch (and Q27 when it fired), play back a compact table — question, the user's words, what was recorded — for Step 4 answers only; sheet rows were already confirmed at Step 2.5 and are not repeated. The recap always waits for "looks good" or a correction: the batch opener invites shorthand and plain-word answers, so nearly every real run involves interpretation, and a conditional show-or-wait rule would itself be an interpretation hazard for agents. One extra turn at the flow's highest-stakes commit is the intended cost. Sequence is fixed and explicit: recap → wait → Category E opt-in → Step 5. "Use defaults for the rest" routes through the recap too, with defaulted rows shown as "(default applied)" — bulk defaulting is the highest-risk interpretation and is the user's one chance to see what "the rest" actually meant. Corrections reuse the existing Step 2.5 override grammar (chosen_by: "user"). The full flow runs the same recap after its final batch. One new validation-checklist item.

Why

Completes the form-UX arc that #127/#170/#169 built, using the two standard patterns those PRs didn't reach: expectation-setting at the entrance (the "takes about 5 minutes, here's what you'll need and what you'll get" box — the best-documented abandonment fix in form design) and the GOV.UK "Check your answers" page at the exit. The flow now reads: know the journey (this PR) → see detected values with sources (#57/#127) → correct in plain language (#170) → see progress (#169) → confirm what was heard (this PR).

Review feedback incorporated (second commit): an earlier draft had a two-branch rule (informational recap for explicit-letter answers, wait for interpreted ones); review pointed out the informational branch would almost never fire since the wizard itself teaches shorthand, and the branch condition itself invited agent divergence — replaced with unconditional wait. Also fixed: explicit recap → Category E → Step 5 ordering, defaults-path recap coverage, and an orientation overpromise ("ready-to-run Terraform" → "Terraform for the in-scope workloads", since BigQuery/specialist gates can defer parts of the stack).

Test plan

• dprint check — clean
• mise run lint:md — 0 errors
• mise run lint:frontmatter — OK (10 phase files)
• No flow-order, gate, or state-machine changes (diff-verified: message additions + one checklist item; sheet hard gate, essentials batching, Category E, and Step 5 untouched)
• Orientation is resume-safe: fires only on fresh runs, never blocks
• "Use defaults for the rest" path routes through the recap (was a bypass in the first commit)
• Manual: fresh run opens with the orientation block, then proceeds to scanning in the same turn
• Manual: answer essentials with "1A 2 skip, spend is about a grand" and confirm the recap shows the interpreted band and the "(default applied)" row, and waits before design

Follow-ups (tracked, not in this PR)

• Machine-checkable recap evidence: metadata.answer_recap: {shown, user_responded} verified at the Clarify handoff gate — checklist items are exactly what this series has watched agents skip; the recap should eventually earn the same fail-closed treatment as the sheet
• clarify-ai-only.md recap parity — AI-only is where plain-word spend/priority answers are most common

Out of scope

• heroku-to-aws / vercel parity (feat(heroku-to-aws): clarify extraction + assumption sheet, decision outcomes, breadcrumbs (gcp parity) #180 territory)

Type of Change

• Enhancement to existing content

Team Folder

• migrate/

[leon1418]

[🤖 AI review 🤖]

Summary: This PR adds two UX improvements to the gcp-to-aws migration flow: (1) a journey orientation block at the start of fresh runs (discover.md Step 0), and (2) an "Answer Recap" (check-your-answers) gate after the final essential question batch in clarify.md Step 4. Both are well-motivated by the PR description's form-UX reasoning — expectation-setting reduces abandonment, and the recap catches misinterpretation before it silently propagates into design constraints.

Design: Sound. The two changes are additive — no existing gates, state machines, or schema changes are touched. The unconditional-wait decision (second commit) is the right call: a conditional informational/wait branch would itself be a source of agent divergence. The fixed sequence (recap → wait → Category E → Step 5) is explicit and unambiguous.

Merge interactions: PRs #181 and #182 both touch clarify.md on main base but in non-overlapping regions — #181 modifies the extraction-detection section (lines 159, 335, 836+) and #182 modifies the Case 1/preferences-reuse section (lines 26-47, 764). Neither touches the Step 4 defaults-handling paragraph (line 475) or the Full Flow variant (line 481) where this PR inserts. Textual merge conflict is unlikely, but a logical interaction exists with #182: if a user resumes with a preferences-superseded.json seed, the recap checklist item (line 832) should still pass — the seeded constraints go through the normal wizard path and the recap fires after the final batch, so this is safe.

No CI checks are reported on this branch (repo uses dprint check, mise run lint:md, mise run lint:frontmatter per the test plan — presumably run locally, not as GitHub Actions). The merge state is BEHIND (needs rebase onto main) but MERGEABLE.

Recommendation: Merge-ready. No blocking findings. One non-blocking observation below. Rebase onto main before merge to resolve BEHIND state. No ordering constraint relative to #181/#182/#184-186 (textually independent).

[leon1418]

[🤖 AI review 🤖]

FYI: The full-flow recap instruction says "all answered questions; skipped/defaulted ones summarized in one line, not per-row" — this is a clear and reasonable compression for the full flow where the table could be very long. However, it means the full-flow recap provides less per-question visibility than the wizard's per-row table, which is slightly surprising given the full-flow user is the one who explicitly opted for more control.

Not a problem for this PR — just worth noting for the follow-up if clarify-ai-only.md parity is being tracked. The wizard-mode recap + the full-flow one-liner approach are both defensible; the asymmetry is intentional and documented.