85 lines
3.1 KiB
Markdown
85 lines
3.1 KiB
Markdown
# Briefing Internals
|
|
|
|
This document describes the implemented briefing package boundary.
|
|
|
|
## Purpose
|
|
|
|
`internal/briefing` builds structured report-specific briefing packages from
|
|
forecast summaries and report metadata. The package currently implements Daily
|
|
Today, Daily Tomorrow, 3-Day Outlook, Weekend Outlook, and Storm Report
|
|
briefing content.
|
|
|
|
## Inputs and Outputs
|
|
|
|
Inputs:
|
|
|
|
- resolved report definition and valid period
|
|
- forecast bundle
|
|
- derived forecast summary or summaries
|
|
- configured units and timezone
|
|
|
|
Output:
|
|
|
|
- `briefing.Package` JSON containing common metadata and report-specific
|
|
briefing content
|
|
|
|
## Boundaries
|
|
|
|
- Briefings are structured weather facts and context for later prompt input.
|
|
- This package does not fetch weather data, compare prior snapshots, build
|
|
`scriptorium` data packages, or render final report prose.
|
|
|
|
## Behavior
|
|
|
|
- Common metadata includes schema version, RunID, report ID, variant, prompt ID,
|
|
generation time, units, timezone, valid period, source location, source
|
|
provenance, hashes, and source warnings.
|
|
- Daily content includes bottom-line inputs, daypart summaries, relevant alerts,
|
|
outdoor window inputs, narrative periods, discussion context, and weather
|
|
story context when available.
|
|
- Daily Tomorrow also includes planning inputs for morning readiness,
|
|
commute/school/workday concerns, and what may change overnight.
|
|
- 3-Day content includes one summary per local day or partial day, with overall
|
|
character, temperature range, precipitation, wind, risk, outdoor-window, and
|
|
alert inputs, plus broader discussion and weather-story context when
|
|
available.
|
|
- Weekend content uses the same daily outlook summaries and adds planning
|
|
inputs for best outdoor windows, worst weather windows, rain/storm timing,
|
|
comfort concerns, and confidence or uncertainty context.
|
|
- Storm content uses the explicit event window and includes event headline
|
|
inputs, hazards, most-likely scenario inputs, reasonable worst-case inputs,
|
|
confidence and uncertainty inputs, watch items, active alerts, relevant
|
|
hourly and narrative forecast periods, and available discussion or weather
|
|
story context.
|
|
- Briefing JSON is written atomically by `briefing.Save`.
|
|
|
|
## Failure Behavior
|
|
|
|
- Daily briefing construction requires a Daily report definition and a derived
|
|
daily forecast summary.
|
|
- 3-Day briefing construction requires a 3-Day report definition and at least
|
|
one derived daily summary in the outlook period.
|
|
- Weekend briefing construction requires a Weekend report definition and at
|
|
least one derived daily summary in the weekend period.
|
|
- Storm briefing construction requires a Storm Report definition and a forecast
|
|
bundle.
|
|
- Save failures include path and operation context.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/briefing/daily_test.go`
|
|
- `internal/briefing/three_day_test.go`
|
|
- `internal/briefing/weekend_test.go`
|
|
- `internal/briefing/storm_test.go`
|
|
- `internal/app/app_test.go`
|
|
- `internal/cli/root_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Weather facts come from normalized and derived source data.
|
|
- Briefing output remains JSON-inspectable.
|
|
- LLM prompt input packaging and `scriptorium` execution remain outside this
|
|
boundary.
|