weatherreporter/docs/internal/changes.md

# Changes Internals

This document describes the implemented structured change comparison boundary.

## Purpose

`internal/changes` compares current and prior structured briefing snapshots and
produces compact change records for prompt input data packages.

## Inputs and Outputs

Inputs:

- prior briefing package
- current briefing package
- configured Recent Changes thresholds

Output:

- ordered `changes.Change` records with type, message, previous value, and
  current value where useful

## Boundaries

- This package compares structured briefing data only.
- It does not read state directly, render Markdown, invoke `scriptorium`, or
  compare generated report text.

## Config Fields Used

The app maps these config fields into comparison thresholds:

- `recent_change.temperature_degrees`
- `recent_change.precip_probability_points`
- `recent_change.wind_gust_miles_per_hour`
- `recent_change.precip_timing_shift_minutes`

## Behavior

Daily, 3-Day, and Weekend comparison currently detect:

- temperature changes crossing configured thresholds
- precipitation probability and timing changes
- alert additions and removals
- peak wind gust changes
- snow, ice, and thunder risk changes

When no prior comparable snapshot exists, the app sends an empty Recent Changes
section in the data package. Daily Today and Daily Tomorrow are compatible for
same-valid-date comparison through the report registry. 3-Day Outlook compares
with prior 3-Day Outlook snapshots for the same valid local date. Weekend
Outlook compares with prior Weekend Outlook snapshots for the same weekend
window.

## Failure Behavior

Daily comparison requires both inputs to contain Daily briefing content. 3-Day
comparison requires both inputs to contain 3-Day briefing content. Weekend
comparison requires both inputs to contain Weekend briefing content.

## Tests

Inspect:

- `internal/changes/daily_test.go`
- `internal/changes/three_day_test.go`
- `internal/changes/weekend_test.go`
- `internal/app/app_test.go`

## Invariants

- Recent Changes are based on structured snapshots, not Markdown report text.
- Comparison thresholds come from configuration.
- The comparison output remains compact enough for prompt input.