Trip-Creation Flow Redesign

Scope: The Agent D companion's chip-driven trip-plan wizard (plan-step-builder.ts and friends). Server-side only — the wizard is fully server-composed and mobile renders cards generically, so the redesign ships on a worker deploy with no app rebuild.

BackgroundContext

Two screenshots (2026-06-12) showed the wizard badly broken for India:

Direction: rethink the chain from first principles — how a person actually creates a trip — and design every path, question, and edge case for both India and international, before any implementation.

Verified prod data grounding this design (audited 2026-06-12 against prod verso-db):

• destination_vibes: India has 14 country-level routes (8-14 days ideal), zero state-scoped routes (zero anywhere). ~40 countries have routes, all 7-14 day range.
• destinations: India has ~477 citylike rows (250 city, 56 heritage, 53 hill-station, 32 pilgrimage, 15 beach, 13 national-park, ...). BUT the metadata is two-tier: every non-city type is ~fully seeded (best_months, vibes, days_needed_min/max), while only 36 of 250 city rows carry any of those — the other 214 are bare name+coords rows (Barsana, Somanathapura, Kushalnagar...). 17 rows are explicit day-trips (days_needed_max = 1: Lepakshi, Sultanpur Bird Sanctuary, ...).
• destinations.transport_from_metros: 186 India rows carry per-metro {km, mode, hours} (e.g. Mussoorie→Delhi: 221km, drive, 3.7h; Coorg→Bangalore: 206km, drive, 3.4h). This is the door-to-door feasibility + chip-annotation source — strictly better than haversine km.
• countries: 102 rows; visa_type populated on 91 (clean enum visa-free / visa-on-arrival / evisa / embassy); popularity_score populated; best_months on only 1 of 102 → country seasons stay in PLAN_SEED.
• regions: 36 India states already exist and are linked via destinations.region_id (Uttarakhand 31 dests, Karnataka 29, Himachal 26, Tamil Nadu 26, Kerala 15, ...). The region table in Part 6 keys onto these rows — no new slugs.
• Mobile already handles range:YYYY-MM-DD:YYYY-MM-DD chip values and renders option chips generically.

Part 1First principles

How people actually start trips

A trip always starts anchored on one of three things, almost never more than one:

A VIBE-first start ("honeymoon", "beach trip") is a sub-case of NEITHER with mood pre-filled.

The constraint cascade

Each answer constrains the next question's OPTIONS — never ask a question whose options ignore prior answers:

trip length  ->  bounds reachable distance (weekend <= ~6-8h door-to-door; a week opens
                 all-India / short-haul intl; 10+ days opens circuits & long-haul)
origin       ->  bounds "nearby" + flight costs
mood         ->  HARD-filters destination types/vibes (beach mood must never
                 surface desert circuits or hill regions); thin pools degrade
                 honestly, never pad with off-mood chips
season/month ->  ranks destinations (monsoon, winter); never blocks — EXCEPT
                 hard closures (national parks shut in monsoon)
destination  ->  determines when-options (its best window), route eligibility,
                 city list, budget ballparks
length+dest  ->  determines whether a multi-city route makes sense at all

Question design rules

1. Never ask what we already know or can infer. Origin from profile/GPS; days from a date range; scope from the entry point; destination from the collection page or typed text. The skip-if-known matrix already exists — keep it.
2. Options must be valid answers to the question. "India" is never an answer to "Where in India?". A 10-day circuit is never an answer for a 3-day trip. If data fails to load, degrade to a plausible static list (PLAN_SEED top destinations), never to a degenerate option.
3. Most-constraining cheap question first. Length before place (when place unknown). Mood only on the open branch.
4. Annotate options with the deciding fact. Nearby: "~1.5h drive · temples". Country: "visa-free · ~4h flight". Season chips: real dates ("This weekend · Jun 13-14").
5. Hard cap the path: ≤ 7 questions to confirm on the longest path; weekend path ≤ 5. Counter monotonic (index never repeats, total never shrinks).
6. Escape hatch on every card ("Pick another" → type it). Free text always works mid-flow (existing digression handling stays).
7. Single source of truth for sequencing — keep the computeStepStates answered/needed discipline; the redesign changes step ORDER and OPTION SOURCES, not the accounting model.
8. Every chip is a promise: a real trip of the asked length. A chip must be a destination people actually book for num_days — its seeded days_needed_min/max range must overlap the trip length, and it must be metadata-complete (best_months + vibes + days_needed all seeded) so we can annotate and season-rank it. Day-trip rows (days_needed_max = 1) and bare name+coords rows never become chips; both stay reachable by typing.
9. Mood is a hard filter, not a rank boost. Once the user says "beach", a Rajasthan circuit or a Himachal region chip is a broken promise. geo_mood — whether from the undecided branch or parsed from typed text ("beach trip in October") — filters every WHERE surface: domestic modes, region chips, intl country tiers, the undecided blend, and route/circuit chips. If the filtered pool is thin, widen reachability and say so honestly ("Beaches need a short flight from Delhi - these fit"), never pad with off-mood chips.
10. Rank by desirability inside feasibility gates — never by raw proximity. Distance/hours decide eligibility; saves, season, mood, and popularity (is_featured, activity_count) decide order. The nearest row is usually a satellite town, not a getaway.

Part 2The flow architecture

Entry points and what they pre-seed

Master step order

Recomputed after every answer; skip-if-known throughout.

SCOPE -> LENGTH -> MOOD* -> ORIGIN** -> WHERE -> WHEN -> DATES
      -> ROUTE*** -> CITIES*** -> WHO -> BUDGET -> PACE**** -> CONFIRM

• * MOOD only on the undecided branch.
• ** ORIGIN promoted here only when needed to anchor nearby suggestions (short domestic, no resolvable coords); otherwise it stays a late skip-if-known step as today.
• *** ROUTE and CITIES are mutually exclusive slot-mates; both skipped when a single destination is already picked.
• **** PACE only when effective days ≥ 5 (existing gate).

Part 3Question catalog

Every question with exact copy, option sources, value formats, merge effect, and skip predicate. Value formats matter because the merge layer and the model/free-text relay both parse them.

Q-SCOPE — "Where to?"

• Options (static): domestic "Within India" (default) / international "Somewhere abroad" / undecided "Help me decide"
• Merge: geo_scope
• Skip: scope pre-seeded (weekend pill, typed "abroad/India"), or country already known.

Q-LENGTH — "How long are you thinking?"

• Options (static): 2-3 "Weekend" / 4-5 "Long weekend" (default for domestic) / 6-8 "About a week" (default otherwise) / 10-14 "10 days - 2 weeks" / escape: pick dates lives on Q-WHEN
• Merge: num_days = midpoint (existing parser).
• Skip: num_days set, or a full date range known.
• Note: replaces today's late num_days step; same card type, same merge case — only sequence position and labels change.

Q-MOOD — "What are you in the mood for?" (undecided branch only)

• Unchanged from today (beach / mountains / city & culture / food & cafes / adventure & nature / surprise me).
• Merge: geo_mood. Skip: not undecided, or mood set.

Q-ORIGIN — "Where are you based?" / "Where are you flying from?"

• Unchanged options (top metros + Pick another). Promotion rule unchanged but now deterministic: short domestic trip + no resolvable coords → promoted before WHERE (length is always known by then, fixing today's dead promotion on the generic path).

Q-WHERE (domestic) — "Where in India?"

The length-aware core. Three modes by num_days:

Mode A — Getaway (≤ 4 days)

Best getaways within reach of origin. suggestNearbyPlaces is rewritten from "nearest rows" to "gates first (hard), desirability second (soft)" — the audit in Context shows distance-sorting alone serves Sultanpur/Barsana to Delhi and Lepakshi to Bangalore.

Hard gates — a candidate must pass ALL of:

1. Metadata-complete: best_months, vibes, days_needed_min/max all seeded. Removes the 214 bare city rows (Barsana, Somanathapura, Kushalnagar...) — they can't be annotated, season-ranked, or length-checked. Malformed JSON in any of these fields counts as missing (skip the row, never throw).
2. Length-fit: days_needed_max ≥ 2 AND days_needed_min ≤ num_days. Removes day-trips (Lepakshi 1-1, Sultanpur 1-1, Alwar & Sariska 1-2) from a weekend card, and 5-day-minimum places from a 2-day card.
3. Reachability in HOURS, not km: when the origin metro is keyed in transport_from_metros (186 rows), use its {mode, hours}: weekend ≤ ~7h door-to-door by drive/train, or ≤ ~2.5h flight; long weekend ≤ ~10h surface or any short flight. Haversine band fallback (≤350km weekend / ≤700km long-weekend) only when tfm or the origin metro is missing — the old 800km cap is a 14-hour Indian drive, not a weekend.
4. Mood-fit when geo_mood is set (see Mood threading below).
5. Open in the target window: for national-park / wildlife types with a known target month outside best_months, exclude — these are hard closures (Ranthambore is shut Jul-Sep), not preferences. All other types: season ranks, never blocks.

Rank within survivors (desirability, NOT distance-ascending): user saves (×5) → season-fit (+3) → mood/vibes match (+2) → popularity (is_featured, activity_count) → mild proximity tiebreak. Then a type-diversity pass: max 1 chip per type among the 4 (never three pilgrimage towns in a row), backfilling from the next-ranked other types. Dedupe by name containment, not just exact match ("Mathura & Vrindavan" vs bare "Vrindavan").

• Chip: photo + name + "3.4h drive · coffee estates" — hours + mode straight from transport_from_metros[origin], flavour word from vibes[0]; "~Xh" haversine estimate only as fallback.
• Value: place:<slug> → merge seeds destination_country='India', the city, and single_city=true (new — this is the screenshot-2 fix; ROUTE + CITIES both skip).
• Concrete bar (assert in tests): Delhi weekend → Mussoorie / Rishikesh / Jim Corbett / Agra (Ranthambore joins on a long weekend via the train band, except Jul-Sep). Bangalore weekend → Coorg / Mysuru / Ooty / Chikmagalur. Sultanpur, Lepakshi, and every bare satellite-town row never appear on a weekend card.

Mode B — Week (5-8 days)

Blended "anchor + region" picks, ranked by saves + season + variety-spread:

• 2-3 anchor destinations that hold a week — derived from data, not a hardcoded list: metadata-complete rows whose [days_needed_min, days_needed_max] overlaps num_days (Goa 3-7, Coorg 3-5, Andamans, ...), ranked saves + season + popularity. Same hard gates as Mode A minus reachability (a week opens all-India; flights are fine). Value place:<slug>, sets single_city=true.
• 1-2 regions (Kerala, Rajasthan, Himachal, Uttarakhand, Ladakh, Northeast) — value state:<slug> where the slug is the existing regions row slug (36 India states already linked via destinations.region_id — don't invent new slugs) → merge sets destination_country='India' + destination_region (draft field already exists, already threaded into the city picker and route query). CITIES step then shows region-scoped cities.
• Region eligibility = the authored region table (Part 6), keyed to regions rows: season window, mood tags (beach → Goa / Kerala / Andamans; mountains → Himachal / Uttarakhand / Ladakh / Sikkim; Rajasthan never under beach), anchor cities, min-days; a region needs ≥ 2-3 metadata-complete cities; saves-boosted.

Mode C — Grand (9+ days)

• Region/circuit-first: regions as in Mode B plus the country-level route step becomes reachable — picking state: goes region → cities; an explicit "Classic circuits" chip (value circuits) routes to Q-ROUTE with the 8-14-day country routes, which finally match the trip length.
• Concretely: 2 regions + 1-2 long anchors (Andamans, Ladakh) + chip "Classic circuits".
• Mood-gated like Mode B; the "Classic circuits" chip is suppressed when geo_mood is set and no route's tags match it — a beach-mood user never sees Golden Triangle.

Q-WHERE (international) — "Which country?"

Length-aware tiers (new), ranked by user saves + season + a new static haul/visa table:

• Chip annotation: "visa on arrival · ~3.5h flight" — visa class from the existing countries.visa_type column (91/102 populated; clean enum visa-free / VoA / e-visa / embassy; authored override only where stale or missing), flight-hours band + mood tags from the small authored INTL_HAUL table. visa.service exists for live data but the column is enough for chips (and deterministic).
• Mood-gated like domestic: geo_mood filters the tier pool via INTL_HAUL.moods (beach → Maldives / Sri Lanka / Thailand / Bali / Mauritius; mountains → Nepal / Georgia / Switzerland; food-cafes → Vietnam / Japan / Italy). A city-break country never shows under beach.
• Top-saved countries still lead when they fit the length tier (and mood, if set); the tiers + mood filter, saves rank. countries.popularity_score is the no-saves tiebreak.
• Value: country name (existing). City-states keep the existing collapse (Singapore → single city).
• Skip: country known.

Q-WHERE (undecided) — "Here are a few ideas - where to?"

• Existing rankForUndecided (saves + season + mood + proximity) gains the length input: ≤4 days → domestic-nearby-weighted + at most 1 short-haul intl; 5-8 → domestic anchors + short/medium intl mix; 10+ → intl-leaning + India circuits.
• Picking a chip resolves the branch (domestic/international) implicitly via the chip's value (place: vs country).

Q-WHEN — adaptive by length and destination

Weekend (≤ 4 days): "When works?"

• "This weekend · Jun 13-15" (upcoming Fri + num_days-1; if today is already Sat/Sun, this chip becomes the current weekend only if the trip still fits, else dropped)
• "Next weekend · Jun 20-22"
• "The weekend after · Jun 27-29"
• "Pick specific dates" (existing client picker)

A range: pick sets dates + month + days → Q-DATES auto-skips (already true). Mobile needs nothing new. Weekend boundaries computed in IST (the worker runs UTC; mirror trip-live-promotion's IST handling).

Longer, destination/region picked

Chips from the picked destination's best_months (or the region's authored window), phrased as windows: "Oct-Feb · best season" (default) / "Apr-Jun" / next concrete month / "Pick specific dates". Falls back to country seasons → month chips. The "When for Lepakshi? → Hill stations (Apr-Jun)" class disappears: country-generic season labels only ever show when the scope IS the country.

Longer, only country known (international)

Existing country season windows from PLAN_SEED — appropriate at country level. Unchanged.

Question copy: "When for {place}?" stays; for weekend mode: "When works?". Skip: month or dates known.

Q-DATES — "Do you have specific dates?"

Unchanged (skips when a range was picked).

Q-ROUTE — "How should this {country} trip feel?"

New gates (the Golden-Triangle fix), in order:

1. Skip if single_city (set by getaway/anchor picks, city-states, destination contexts).
2. Skip if destination_cities non-empty (cities already chosen — typed intent, prior step).
3. Skip if num_days < 5.
4. Duration filter: only routes with ideal_duration_days ≤ num_days + 3; rank by |ideal - num_days|, classic first among fits; if zero routes fit → skip to Q-CITIES.
5. Region-scoped routes when destination_region set; a region with no region routes (today: all of them) skips ROUTE and goes to CITIES scoped to the region — never falls back to country circuits (today's fallback is the bug).

• Chip shows: title, city path, tagline, "ideal 8-10 days" annotation (new, from ideal_duration_days).
• Note: when ROUTE is skipped by gates 1-3, KIND (vibe) also stays skipped if a destination is picked — the trip's feel is implied; fewer questions. KIND remains the fallback only for country-wide trips in countries with no routes (existing behaviour).

Q-CITIES — "Which cities in {X}?"

Existing behaviour, now also region-scoped via destination_region (plumbing already exists: getCityOptionsForPlan({scopeRegion})). Day-scaled pre-check unchanged. Skipped when single_city or cities set.

Q-WHO / Q-BUDGET / Q-PACE / Q-CONFIRM

Unchanged (budget chips already country+days aware; pace keeps its ≥5-day gate).

Part 4Path walkthroughs (concrete)

Part 5Edge-case matrix

Part 6Data & content work-items (separate from code)

1. INTL_HAUL static table (~40 countries): flight-hours-band from India + mood tags. Visa class now comes from the existing countries.visa_type column (91/102 populated) — author overrides only where it's stale/missing. Authored once, lives next to PLAN_SEED.
2. India region table (~10 entries): keyed to existing regions slugs (36 state rows, already linked via destinations.region_id — don't invent parallel slugs): season window, mood tags, anchor cities, min-days. Powers WHERE-B/C region chips and the region mood gate.
3. MOOD_TO_VIBES mapping (~6 moods × the seeded vibe vocabulary): extends the existing MOOD_TO_TYPES so mood matching sees vibes too (Rishikesh: type city, vibes adventure/wellness — type alone misses it).
4. Prod destinations audits/backfills (none block the code ship; the gates make missing data safe):
   • Backfill best_months/vibes/days_needed_min/max on the ~50 most chip-worthy of the 214 bare city rows (Dehradun, Coonoor, Sakleshpur...); the rest stay gated out harmlessly.
   • transport_from_metros coverage is 186/477: ensure every Mode-A candidate within haversine range of the 8 keyed metros has tfm, else good getaways silently fall to the conservative km fallback.
   • Audit best_months on all national-park/wildlife rows to correctly encode monsoon closures (Ranthambore, Corbett zones, Kaziranga) — gate 5 trusts this field.
   • Verify all 50 INDIA_TOP_DESTINATIONS slugs resolve to metadata-complete seeded rows — they are the failure fallback, and a fallback that fails the gates defeats the design.
5. (Later, optional) state-scoped destination_vibes routes for Rajasthan/Kerala/Himachal circuits — unlocks region ROUTE cards; design already accommodates their absence.
6. (Later, optional) Indian holiday calendar → "long weekend of Aug 15" chips on Q-WHEN.

Part 7Implementation outline (later phase; for sizing only)

All server-side, in workers/api/src/services/agent-d/ (+ destination.service.ts); ships on worker deploy, no app rebuild:

• plan-step-builder.ts — move num_days in the step table; rewrite whereOptionsFor (3 domestic modes, intl tiers, delete the "India" chip); whenOptionsFor weekend + best-months modes; ROUTE needed gates; breadcrumb region row.
• plan-step-merge.ts — place: sets single_city; new state: + circuits values.
• start-plan-core.ts — lazy loaders for the new WHERE modes + WHEN best-months; unify BuildStepOptions construction across entry points (counter fix).
• destination-suggester.ts — rewrite suggestNearbyPlaces (hard gates: metadata-complete / length-fit / hours-reachability via transport_from_metros / mood / closure; desirability rank; type-diversity + containment dedupe); new suggestIndiaWeek/Grand blends; length + mood inputs to rankForUndecided; MOOD_TO_VIBES beside MOOD_TO_TYPES.
• seasons.ts — weekend range: chip builder (IST); destination best-months chips.
• destination.service.ts — getRouteOptionsForPlan duration filter + no-country-fallback-when-region flag.
• agent-d.routes.ts — stale-step idempotent re-emit (edge 17).
• New static data: INTL_HAUL, India region table (in plan-seed-data.ts).
• Tests: extend plan-flow-chained.test.ts to walk P1-P10 asserting question order, option invariants ("India" never an option; route never shown <5d or with cities picked), and counter monotonicity; unit tests for the new suggesters/season chips/merge cases — including fixture-driven gate tests (a day-trip row, a bare row, a monsoon-closed park, a beach-mood pool) asserting each is excluded.

Sign-offAcceptance criteria (when implemented)

• The P1-P10 walkthroughs hold exactly (question order, options class, skip behaviour).
• Invariants enforced by tests: "India" never appears as a WHERE option; ROUTE never shows when single_city, cities picked, or num_days < 5; route chips always satisfy the duration filter; progress counter monotonic on every path.
• Data-grade invariants enforced by tests: no chip from a row missing best_months/vibes/days_needed; no days_needed_max=1 row on a ≥2-day card; weekend chips inside the hours band; geo_mood='beach' never yields a chip, region, or route without beach affinity (the "Rajasthan under beach" test); the Delhi-weekend fixture surfaces Mussoorie-class getaways and none of Sultanpur / Barsana / Vrindavan.
• On-device validation via dev build: "Plan a trip" and "Plan a weekend" pills from a Bangalore profile AND a Delhi profile (the two metros fail differently today).