Repository Docs & Knowledge Base

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.

1. Identify seasonal demand patterns, including:
2. weekday vs weekend behavior
3. recurring weekly cycles
4. recurring monthly demand patterns.

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

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

1. Enrich the dataset using external signals, including:
2. holidays and public events
3. seasonal periods
4. local events such as sports games or festivals.

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

1. Evaluate how past holidays and events affected demand, identifying whether they caused:
2. revenue spikes
3. revenue drops
4. demand shifts between days.

1. Adjust the baseline forecast values to account for:
2. seasonal demand patterns
3. detected growth or decline trends
4. upcoming holidays or events
5. contextual signals such as weather.

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

1. Output constraints:
2. return adjusted forecast data only
3. do not include explanations, reasoning, or methodology.

1. Minimize database usage:
2. prefer aggregated summaries
3. 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.