weatherreporter/docs/internal/prompt-input.md

# Prompt Input Internals

This document describes the implemented prompt input package boundary.

## Purpose

`internal/promptinput` converts a structured briefing package into the
`data_package` JSON file passed to `scriptorium` prompts.

## Inputs and Outputs

Input:

- `briefing.Package` containing Daily-family, 3-Day Outlook, Weekend Outlook,
  or Storm Report content

Output:

- `promptinput.Package` JSON with report metadata, briefing content, source
  warnings, RunID, and a Recent Changes section.

## Boundaries

- This package owns the prompt input schema and required-field validation.
- It does not fetch weather data, compute forecast summaries, compare prior
  snapshots, or invoke `scriptorium`.

## Behavior

- `promptinput.Build` copies report metadata from the briefing package.
- `promptinput.Validate` rejects missing or inconsistent required fields before
  render preflight.
- `promptinput.Save` writes JSON atomically where practical.
- Recent Changes is present as an `items` list. It is empty when no prior
  comparable snapshot exists or no meaningful changes are detected.

## Failure Behavior

Validation errors name the missing or inconsistent field. Save failures include
the filesystem operation and path context.

## Tests

Inspect:

- `internal/promptinput/package_test.go`
- `internal/changes/daily_test.go`
- `internal/app/app_test.go`

## Invariants

- Prompt input data remains structured JSON.
- Briefing metadata and top-level report metadata must agree.
- Recent Changes is not inferred from rendered report text.