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:

```yaml
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.