date-optimization

name	date-optimization
description	Use when traveler has flexible dates and wants to find the cheapest departure/return combination. Triggers on cheapest day to fly, flexible dates, when to book, price calendar.

Date Optimization - Quét Ngày Bay Tối Ưu

Purpose

Find the optimal departure and return dates within a flexible range. Instead of checking prices day-by-day, this skill builds a complete price matrix and identifies the cheapest combinations with clear explanations.

Input Required

From orchestrator profile:

• origin, destination (IATA codes)
• departure_date (target)
• return_date (target, if round-trip)
• flexibility: low (±2d) | medium (±7d) | high (±14d)

Execution Steps

Step 1: Build Date Range

Calculate the full search window:

• Depart window: departure_date - flex_days to departure_date + flex_days
• Return window: return_date - flex_days to return_date + flex_days
• Total combinations: (flex_days * 2 + 1)² for round-trip

Example (±7 days): 15 × 15 = 225 date combinations to evaluate.

Step 2: Apply Pricing Patterns (AI-Knowledge Mode)

Use these established pricing patterns to estimate relative costs:

Day-of-week patterns:

• Tuesday, Wednesday: typically 15-25% cheaper (lowest demand)
• Friday, Sunday: typically 10-20% more expensive (weekend travel peaks)
• Saturday departure: sometimes cheap (contra-flow)

Seasonal patterns:

• Refer to references/pricing-patterns.md for route-specific seasonality

Advance purchase effect:

• 21+ days ahead: best domestic fares
• 45-60 days ahead: best international fares
• < 7 days: premium pricing (last-minute surge)
• Exception: LCCs sometimes release last-minute deals

Holiday surcharges:

• Vietnamese holidays: Tet (+50-100%), 30/4-1/5 (+30-50%), 2/9 (+20-30%)
• US holidays: Thanksgiving, Christmas, July 4th (+30-60%)
• School holidays: June-August (+20-40% on leisure routes)

Step 3: Score Each Combination

For each date pair, calculate a relative price score (1-10):

score = base_pattern + day_of_week_factor + seasonal_factor + advance_purchase_factor

Step 4: Generate Output

Format: Price Heatmap (text-based)

           Return →  Mon  Tue  Wed  Thu  Fri  Sat  Sun
Depart ↓
  Mon 15/6           $$   $    $    $$   $$$  $$   $$$
  Tue 16/6           $    $    $    $    $$   $$   $$
  Wed 17/6           $    $    $    $    $$   $$   $$$
  Thu 18/6           $$   $    $    $$   $$$  $$   $$$
  Fri 19/6           $$$  $$   $$   $$   $$$  $$$  $$$

Legend: $ = cheapest tier, $$ = mid-range, $$$ = most expensive

TOP 3 Recommendations:

For each recommendation, provide:

1. Specific dates (depart + return)
2. Estimated savings vs target date
3. WHY this combination is cheap (not just "it's cheaper")
   • Example: "Tuesday departure avoids weekend premium. Mid-week return catches post-business-travel low."
4. Trade-off: what user gives up (e.g., "1 fewer weekend day at destination")

Step 5: Pass Forward

Send to flight-search skill:

optimal_dates: [
  {depart: "2026-06-16", return: "2026-06-25", confidence: "high"},
  {depart: "2026-06-17", return: "2026-06-24", confidence: "high"},
  {depart: "2026-06-15", return: "2026-06-23", confidence: "medium"}
]

API-Enhanced Mode

When Kiwi Tequila API is available, replace Step 2-3 with real price data:

• Use /v2/search with date_from and date_to parameters
• Set fly_days to cover the full flexibility range
• Real prices replace pattern-based estimates

Limitations

• AI-Knowledge mode provides relative rankings, not exact prices
• Holiday pricing can be unpredictable (flash sales, last-minute changes)
• Pattern accuracy decreases for niche routes with irregular schedules