spec: add timeseries-forecast-uncertainty specification (#3191)

## New Specification: `timeseries-forecast-uncertainty`

Related to #3188

---

### specification.md

# timeseries-forecast-uncertainty: Time Series Forecast with Uncertainty
Band

## Description

A time series plot that displays historical observed data followed by a
forecast projection with confidence intervals or uncertainty bands. The
plot clearly distinguishes between the historical period and the
forecast period using a vertical line marker, with shaded bands
representing different confidence levels (typically 80% and 95%). This
visualization is essential for communicating prediction uncertainty in
forecasting applications, helping stakeholders understand both the
expected values and the range of possible outcomes.

## Applications

- Visualizing sales and demand forecasting with confidence intervals for
inventory planning
- Displaying stock price or financial indicator predictions with
uncertainty ranges for risk assessment
- Communicating weather forecast uncertainty with multiple confidence
bands
- Presenting economic projections with confidence intervals for policy
decisions
- Illustrating capacity planning forecasts with uncertainty bounds for
resource allocation

## Data

- `date` (datetime) - Time index covering both historical and forecast
periods
- `actual` (numeric) - Historical observed values (null/NaN for forecast
period)
- `forecast` (numeric) - Predicted values (typically starts where actual
ends, may overlap slightly)
- `lower_80` (numeric) - Lower bound of 80% confidence interval
- `upper_80` (numeric) - Upper bound of 80% confidence interval
- `lower_95` (numeric) - Lower bound of 95% confidence interval
- `upper_95` (numeric) - Upper bound of 95% confidence interval
- Size: 50-200 total points (30-150 historical + 10-50 forecast)
- Example: Monthly sales data with 3 years history and 6-month forecast
from Prophet or ARIMA model

## Notes

- Use a solid line for historical data and a distinct style (dashed or
different color) for forecast
- Mark the forecast start with a vertical line or shaded region
- Use nested shaded bands for confidence intervals: darker for 80%,
lighter for 95%
- Semi-transparent fills (alpha 0.2-0.4) allow bands to overlap without
obscuring data
- Include a clear legend identifying historical data, forecast, and
confidence levels
- Consider using a consistent color family (e.g., blue for historical,
orange for forecast)

---

**Next:** Add `approved` label to the issue to merge this PR.

---
:robot: *[spec-create
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/20788185801)*

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/timeseries-forecast-uncertainty/specification.md

@@ -0,0 +1,34 @@
+# timeseries-forecast-uncertainty: Time Series Forecast with Uncertainty Band
+
+## Description
+
+A time series plot that displays historical observed data followed by a forecast projection with confidence intervals or uncertainty bands. The plot clearly distinguishes between the historical period and the forecast period using a vertical line marker, with shaded bands representing different confidence levels (typically 80% and 95%). This visualization is essential for communicating prediction uncertainty in forecasting applications, helping stakeholders understand both the expected values and the range of possible outcomes.
+
+## Applications
+
+- Visualizing sales and demand forecasting with confidence intervals for inventory planning
+- Displaying stock price or financial indicator predictions with uncertainty ranges for risk assessment
+- Communicating weather forecast uncertainty with multiple confidence bands
+- Presenting economic projections with confidence intervals for policy decisions
+- Illustrating capacity planning forecasts with uncertainty bounds for resource allocation
+
+## Data
+
+- `date` (datetime) - Time index covering both historical and forecast periods
+- `actual` (numeric) - Historical observed values (null/NaN for forecast period)
+- `forecast` (numeric) - Predicted values (typically starts where actual ends, may overlap slightly)
+- `lower_80` (numeric) - Lower bound of 80% confidence interval
+- `upper_80` (numeric) - Upper bound of 80% confidence interval
+- `lower_95` (numeric) - Lower bound of 95% confidence interval
+- `upper_95` (numeric) - Upper bound of 95% confidence interval
+- Size: 50-200 total points (30-150 historical + 10-50 forecast)
+- Example: Monthly sales data with 3 years history and 6-month forecast from Prophet or ARIMA model
+
+## Notes
+
+- Use a solid line for historical data and a distinct style (dashed or different color) for forecast
+- Mark the forecast start with a vertical line or shaded region
+- Use nested shaded bands for confidence intervals: darker for 80%, lighter for 95%
+- Semi-transparent fills (alpha 0.2-0.4) allow bands to overlap without obscuring data
+- Include a clear legend identifying historical data, forecast, and confidence levels
+- Consider using a consistent color family (e.g., blue for historical, orange for forecast)

plots/timeseries-forecast-uncertainty/specification.yaml

@@ -0,0 +1,33 @@
+# Specification-level metadata for timeseries-forecast-uncertainty
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: timeseries-forecast-uncertainty
+title: Time Series Forecast with Uncertainty Band
+
+# Specification tracking
+created: 2026-01-07T16:20:29Z
+updated: null
+issue: 3188
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/reference/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - line
+    - area
+  data_type:
+    - timeseries
+    - numeric
+    - datetime
+  domain:
+    - general
+    - business
+    - finance
+    - statistics
+  features:
+    - temporal
+    - forecast
+    - uncertainty
+    - confidence-interval
+    - annotated