weatherreporter/docs/internal/forecast-derivation.md

Forecast Derivation Internals

This document describes the implemented deterministic forecast summarization boundary.

Purpose

internal/forecast converts a normalized forecast bundle into inspectable daily and multi-day daypart summaries. These summaries are structured data for later briefing builders; they are not rendered report text.

Inputs and Outputs

Inputs:

• forecast.Bundle
• local date and timezone
• report period, for multi-day summaries
• configured daypart definitions with HH:MM start and end values

Output:

• forecast.DailySummary with a civil-day period, daypart summaries, selected narrative periods, alert overlaps, discussion context, source warnings, and source provenance.
• forecast.BuildPeriodDailySummaries output with one clipped daily summary for each local day or partial day in a report period.

Boundaries

• This package groups and summarizes already-normalized forecast data.
• It does not fetch weather data, resolve report definitions, compare prior snapshots, build prompt input packages, or call scriptorium.

Behavior

• Daypart windows use half-open intervals.
• Overnight dayparts are supported when the end clock is not after the start clock.
• Hourly forecast periods are selected by overlap with the daypart window.
• Each daypart computes temperature range, apparent-temperature range, maximum precipitation probability, peak wind speed, peak wind gust, dominant condition, notable conditions, and basic weather indicators.
• Alerts are selected by overlap with the daily period and each daypart.
• Narrative periods and discussion context are selected as broader source context for later briefing builders.
• Multi-day period summaries clip the first and last local days to the resolved report period before selecting hourly periods and alerts.

Failure Behavior

• Missing hourly forecast data returns an error.
• Invalid daypart definitions return actionable parse errors.
• Alert records without parseable RFC3339 start/end fields are skipped.

Tests

Inspect:

• internal/forecast/derive_test.go
• internal/timeutil/periods_test.go

Invariants

• Weather facts come from normalized source data, not generated prose.
• Outputs remain JSON-inspectable.
• Forecast derivation remains independent of CLI, HTTP adapters, and report registry behavior.