# 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.