weatherreporter/docs/internal/prompt-input.md

Prompt Input Internals

This document describes YAML prompt data package construction in internal/promptinput.

Purpose

internal/promptinput converts report metadata, ordered module outputs, Recent Changes, and source warnings into the data_package file passed to Scriptorium.

The persisted data package is YAML with schema version weatherreporter.data_package.v3. It is separate from the JSON module snapshot used for inspection and comparison. Data packages serialize each module output's prompt export value, not necessarily the full rich module value saved in the module snapshot.

Inputs And Outputs

Inputs:

• report metadata from app/state orchestration
• module.Snapshot
• optional []changes.Change

Outputs:

• promptinput.Package with schema version, RunID, report metadata, named module stanzas grouped for prompt presentation, Recent Changes, and source warnings
• YAML bytes from promptinput.MarshalYAML
• YAML file written atomically by promptinput.Save

The YAML shape includes:

schema_version: weatherreporter.data_package.v3
run_id: <run_id>
report:
  id: <report_id>
  prompt_id: <prompt_id>
briefing:
  metadata: {}
  applicable_risk_products:
    alert_digest: {}
    spc_convective_outlooks: {}
  derived_summaries:
    derived_daily_summary: {}
    derived_daypart_summaries: {}
    precip_timing: {}
    outdoor_windows: {}
  narrative_products:
    narrative_forecast: {}
    area_forecast_discussion: {}
    spc_convective_discussion: {}
    weather_story: {}
  raw_data:
    current_conditions: {}
    hourly_forecast: {}
recent_changes:
  items: []

The briefing mapping keeps metadata directly under briefing and groups weather module stanzas under prompt-facing categories. This grouping is a YAML presentation concern only: module snapshots remain flat, and loaded promptinput.Package values expose flat stanza names in Briefing.Values. Within each category, stanza order follows the module snapshot output order. Prompt-facing module intervals use local period_begins and period_ends labels; canonical report metadata and source timestamps remain structured timestamps where applicable.

Module Export Boundary

Data packages are curated prompt inputs. They are not full template render contexts and should not be treated as a dump of every field available to Go templates.

When module outputs are built by internal/briefing, the registry attaches a runtime prompt export value. internal/promptinput serializes output.DataPackageValue() for each stanza. That helper prefers the runtime prompt export and falls back to the rich Value when no prompt export is set, which keeps loaded snapshots and hand-built tests usable.

Modules without custom export policy use pass-through behavior. Modules with custom exports currently include:

• current_conditions: omits lower-case condition text and duplicate wind-direction text.
• hourly_forecast: omits hour labels, lower-case description text, and the template precipitation-mention helper while keeping forecast facts.
• derived_daypart_summaries: omits deterministic sentence-construction helpers while keeping daypart period, condition, temperature trend, precipitation, wind, notable-condition, hazard, and alert-relevance facts.

The rich module snapshot and generated-template render context still contain the helper fields used by deterministic Markdown templates.

Daily Report, Today Report, Tomorrow Report, and Hourly Report module snapshots use the same package schema and categories when converted into prompt input. The default hourly module list places precip_timing under derived_summaries, alert and SPC outlooks under applicable_risk_products, AFD/SPC discussion/weather story under narrative_products, and current/hourly data under raw_data. It does not include civil-day summary stanzas. Generated-text and render context artifacts are produced later in app orchestration and are not part of the YAML data package.

The default Daily, Today, and Tomorrow module lists include civil-day summary stanzas, planning stanzas, and hourly_forecast in the data package before structured GeneratedText is requested from Scriptorium. Daily uses daily_planning, Today uses today_planning, and Tomorrow uses tomorrow_planning.

Current categories are:

• applicable_risk_products: location-applicable alerts, warnings, outlooks, and similar risk products. Current stanzas include alert_digest and spc_convective_outlooks.
• derived_summaries: deterministic summaries and calculated report facts.
• narrative_products: official narrative text products and forecast stories. Current stanzas include narrative_forecast, area_forecast_discussion, spc_convective_discussion, and weather_story.
• raw_data: minimally transformed underlying weather data.

Boundaries

• This package owns prompt package schema, YAML marshaling, YAML loading, and validation.
• It does not fetch weather data, derive forecast summaries, execute modules, choose module prompt export shapes, find prior snapshots, compare changes, choose artifact paths, or invoke Scriptorium.

Config Fields Used

None directly. Config-derived values such as timezone, units, and prompt location are already present in report metadata and module stanzas before this package runs.

External Adapters Used

None.

State Or Manifest Behavior

promptinput.Save writes YAML atomically. Managed workspace paths are owned by internal/state.

Skip And Resume Behavior

None. Recent Changes is always present as an items list and may be empty.

Failure Behavior

Validation fails before render preflight when required top-level fields are missing or inconsistent, when the valid period is invalid, or when no module stanzas are present. Save failures include filesystem operation and path context.

Tests

Inspect:

• internal/promptinput/package_test.go
• internal/app/app_test.go

Invariants

• Scriptorium receives structured YAML through --input data_package=<path>.
• Module stanza order is deterministic within each prompt-facing category.
• Every non-metadata module stanza has exactly one prompt-input category.
• Data-package stanzas use curated module prompt exports when present and rich values only as pass-through or fallback values.
• Data packages are narrower than generated-template render contexts.
• Recent Changes are provided by internal/changes; this package does not infer changes from rendered report text.