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, an ordered module snapshot,
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.v2`. It is separate from the JSON module snapshot
used for inspection and comparison.

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

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 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. Today uses `today_planning`;
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,
  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.
- Recent Changes are provided by `internal/changes`; this package does not
  infer changes from rendered report text.