weatherreporter/docs/internal/briefing.md

Module Builder Internals

This document describes module builder behavior in internal/briefing.

Purpose

internal/briefing turns report metadata, collected weather data, and derived forecast facts into prompt-facing module outputs. The package also owns the module registry used to validate report composition and config overrides.

Module outputs are structured prompt inputs. They are not rendered report prose and they are not persisted by this package.

Inputs And Outputs

Inputs:

• resolved report definition, generation time, timezone, and valid period
• collected facts built from weatherdata.Bundle
• derived daily, daypart, precipitation, alert, and storm-window facts where required
• configured units, timezone, and descriptive location context
• typed module options from report defaults or config overrides

Outputs:

• ModuleDefinition values with module ID, stanza name, option type, supported reports, fact requirements, missing-data behavior, and builder
• module.Output values for source-oriented stanzas: metadata, current_conditions, narrative_forecast, hourly_forecast, alert_digest, spc_convective_outlooks, area_forecast_discussion, spc_convective_discussion, and weather_story
• module.Output values for derived stanzas: derived_daily_summary, derived_daypart_summaries, precip_timing, outdoor_windows, today_planning, tomorrow_planning, and daily_planning

Every registered composition entry has a builder. Unknown or unimplemented module IDs fail validation instead of being skipped.

Daily Report supports the Daily-style civil-day modules plus daily_planning and hourly_forecast; those outputs feed the dated Daily GeneratedText prompt package and embedded Markdown template.

Tomorrow Report supports the Daily-style civil-day modules plus tomorrow_planning and hourly_forecast; those outputs feed the Tomorrow GeneratedText prompt package and embedded Markdown template.

Today Report supports the Daily-style civil-day modules plus today_planning and hourly_forecast; those outputs feed the Today GeneratedText prompt package and embedded Markdown template.

today_planning is a Today-specific deterministic planning stanza with morning readiness, commute/school/workday concerns, outdoor planning, and late-day change-watch fields. It is compatible with report.Today only.

daily_planning is a dated Daily deterministic planning stanza with morning readiness, commute/school/workday concerns, and overnight change-watch fields. It is compatible only with the daily report ID value. The default Daily Report composition includes it.

Hourly Report supports source and valid-period modules that operate over its rolling six-hour period: metadata, current_conditions, hourly_forecast, precip_timing, alert_digest, spc_convective_outlooks, area_forecast_discussion, spc_convective_discussion, and weather_story. It does not support daily/daypart-only modules such as derived_daily_summary, derived_daypart_summaries, outdoor_windows, today_planning, tomorrow_planning, or daily_planning.

Prompt-facing module values use local, human-readable date and time labels where the LLM is expected to reason about report content. Canonical timestamps remain in report metadata, source provenance, and integration artifacts.

Boundaries

• This package selects and shapes already-collected weather facts for prompts.
• It validates module composition against report compatibility and option types.
• It does not fetch weather data, compare prior snapshots, write module snapshots, build YAML data packages, invoke Scriptorium, or write workflow metadata.

Config Fields Used

The app layer passes effective units, timezone, and location context into the module context. internal/facts consumes daypart configuration before module builders run. Configured location values are prompt context only; Weather API sourceLocationId and sourceLocation remain source provenance.

area_forecast_discussion uses optional sections configuration to include a subset of discussion fields. Hourly Report defaults this module to key_messages and short_term.

spc_convective_outlooks uses collected SPC run metadata and derived report-period outlooks. It emits checked: true for a successfully fetched empty run, reports outlook_count, and includes prompt-facing outlook fields such as risk label, period_begins, period_ends, image URL, and whether the outlook contains the configured location. It also emits a curated risk_digest for categorical outlooks that overlap the report period, contain the location, and meet the configured-in-code minimum severity for report rendering. It does not emit GeoJSON geometry, source URL, expiration time, or severity rank.

Prompt-facing module intervals use friendly local period_begins and period_ends labels. Canonical report metadata, source provenance, issued_at, updated_at, and point-in-time fields remain separate.

spc_convective_discussion uses the same derived report-period outlooks and discussion records. It is omitted unless at least one retained categorical outlook for the same SPC day has severity rank 3 or higher and matching discussion text exists.

External Adapters Used

None directly.

State Or Manifest Behavior

None. internal/app collects module outputs into a module.Snapshot, and internal/state persists that snapshot.

Skip And Resume Behavior

None. Builders either emit 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.
• Composition validation rejects unknown modules, duplicate modules, incompatible report/module combinations, duplicate stanza names, and invalid option shapes.
• 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.
• SPC convective outlook output distinguishes checked empty outlook data from missing outlook source data and omits GeoJSON geometry from prompt-facing fields.
• SPC convective discussion output is omitted unless a retained outlook has severity rank 3 or higher and matching discussion text is available.

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.
• Prompt input packaging and Scriptorium execution remain outside this package.