weatherreporter/docs/internal/briefing.md

Module Builder Internals

This document describes the implemented module builder boundary in internal/briefing.

Purpose

internal/briefing builds prompt-facing module values from resolved report metadata, collected weather data, and derived forecast facts. These values are curated prompt inputs, not rendered report prose or durable report snapshots.

Inputs And Outputs

Inputs:

• resolved report definition, generation time, timezone, and valid period
• weatherdata.Bundle with source provenance and warnings
• derived daily, period, or storm-window facts where required
• configured units, timezone, and descriptive location context

Outputs:

• module registry definitions for known module IDs, stanza names, option shapes, fact requirements, report compatibility, and missing-data behavior
• source-oriented module outputs for metadata, current_conditions, alert_digest, area_forecast_discussion, and weather_story
• derived module outputs such as daily summaries, daypart summaries, precipitation timing, outdoor windows, and tomorrow planning
• optional current conditions and weather story module outputs when those Weather API sources are available

Boundaries

• This package selects and shapes weather facts for prompts.
• It owns module registry validation and module builder behavior.
• It does not fetch weather data, compare prior snapshots, build data_package files, invoke Scriptorium, or write workflow metadata.

Config Fields Used

The package receives configured units and timezone from the app layer. Daypart configuration is consumed by internal/facts before module builders run. Configured location values are prompt context only; Weather API sourceLocationId and sourceLocation remain source provenance. Current conditions are copied from the normalized /conditions/current bundle source only; observation station and timestamp fields remain provenance.

External Adapters Used

None directly.

State Or Manifest Behavior

None. Module snapshots and prompt input data packages are persisted by internal/state and composed by internal/app.

Skip And Resume Behavior

None. Builders either return a module output, omit optional unavailable data, or return an error for invalid required inputs.

Failure Behavior

• Required derived modules return errors when their dependent facts are not available.
• Module registry construction rejects duplicate module IDs and duplicate stanza names.
• Module composition validation rejects unknown modules, duplicate modules, incompatible report/module combinations, and invalid typed options.
• Source-oriented module builders omit missing optional current conditions, forecast discussion, and weather story stanzas.
• Alert digest output distinguishes checked empty alert data from missing alert source data.

Tests

Inspect:

• internal/briefing/base_modules_test.go
• internal/briefing/derived_modules_test.go
• internal/briefing/modules_test.go
• internal/app/app_test.go

Invariants

• Module outputs contain structured weather facts and source context.
• Common metadata includes RunID, report ID, prompt ID, valid period, source provenance, source hashes, source warnings, and configured prompt location.
• LLM prompt input packaging and Scriptorium execution remain outside this boundary.