---
id: 3e9b5c41-6a27-4f7c-b0d8-9d2e6f1a8c73
name: Incorporate seasonality, trends, and special events
kind: ForecastEnhancement
cron: 0 0 6 * * *
analysis_window: 90d
comparison_periods: [7d, 28d]
---

Incorporate **seasonality, long-term trends, and special events** into sales forecasting to improve prediction accuracy and better reflect real-world demand fluctuations.

The process should analyze historical sales behavior and adjust baseline forecasts to reflect **predictable seasonal patterns, demand trends, and event-driven demand changes**.

The output must contain **adjusted forecast data only**, without explanations or descriptions of methodology.

## Known Tables & Columns

### `curated.pos_transaction_items`
- item (integer) - menu item identifier — references itm.id  
- bohname (varchar) - menu item name — for item name join itm on gnditem.item = itm.id and use itm.longname  
- price (decimal) - current selling price  
- cost (decimal) - estimated cost of item — not in gnditem, join itm on gnditem.item = itm.id and use itm.cost  
- revid (integer) - revenue center identifier — for revenue center name join rev on gnditem.revid = rev.id and use rev.name  

### `curated.pos_hourly_sales`
- dob (date) - transaction date  
- starthour (integer) - start of hourly sales window  
- stophour (integer) - end of hourly sales window  
- keyvolume (integer) - quantity sold — closest available field in gndslsum  
- revid (integer) - revenue center identifier — join rev on gndslsum.revid = rev.id and use rev.name  
- amount (decimal) - total sales value  

### `curated.pos_transactions`
- dob (date) - transaction date  
- revid (integer) - revenue center identifier — join rev on gndrevn.revid = rev.id and use rev.name  
- amount (decimal) - revenue generated — represents the amount per check row; aggregate with SUM(amount) for total revenue  
- check (integer) - order identifier — derive total orders using COUNT(DISTINCT check)  

## Analysis Approach

1. Extract historical sales data from the last **90 days** using `curated.pos_hourly_sales`.

2. Identify **seasonal demand patterns**, including:
   - weekday vs weekend behavior
   - recurring weekly cycles
   - recurring monthly demand patterns.

3. Detect **long-term sales trends**, such as:
   - gradual growth in revenue
   - gradual decline in demand
   - sustained shifts in purchasing behavior.

4. Detect **recent anomalies** within the historical window such as:
   - unusual spikes or drops in sales
   - short-term effects caused by promotions or special events.

5. Enrich the dataset using **external signals**, including:
   - holidays and public events
   - seasonal periods
   - local events such as sports games or festivals.

6. Retrieve short-term contextual signals using the `get_weather_forecast` tool to determine whether upcoming demand may deviate from historical baselines.

7. Evaluate how **past holidays and events affected demand**, identifying whether they caused:
   - revenue spikes
   - revenue drops
   - demand shifts between days.

8. Adjust the **baseline forecast values** to account for:
   - seasonal demand patterns
   - detected growth or decline trends
   - upcoming holidays or events
   - contextual signals such as weather.

9. Ensure adjustments remain **stable and realistic**, avoiding overfitting to short-term anomalies.

10. Output constraints:
   - return **adjusted forecast data only**
   - **do not include explanations, reasoning, or methodology**.

11. Minimize database usage:
   - prefer aggregated summaries
   - avoid requesting more than **3 queries** unless necessary.

## Output Format

Return **adjusted forecast values** reflecting seasonality, trends, and special-event demand effects.

No explanations or narrative text should be included in the output.