eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Add 3-Day Outlook generation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-29 18:08:50 +00:00
parent 19513e42c1
commit 4c9d396f9b
24 changed files with 927 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/cli.md
View File

@@ -1,11 +1,12 @@
# Weatherreporter CLI
`weatherreporter generate daily`, `weatherreporter generate tomorrow`, and
`weatherreporter run evening` currently write Daily-family Markdown reports
`weatherreporter generate daily`, `weatherreporter generate tomorrow`,
`weatherreporter generate three-day`, `weatherreporter run evening`, and the
Sunday `weatherreporter run morning` path currently write Markdown reports
through `scriptorium`, after writing managed preparation artifacts and running
`scriptorium render` as a preflight check. Other report generation and scheduled
runs still resolve configuration, report definitions, and valid periods, then
return a not-implemented error.
`scriptorium render` as a preflight check. Unsupported report generation and
scheduled runs still resolve configuration, report definitions, and valid
periods, then return a not-implemented error.
## Shortest Useful Command
@@ -27,6 +28,12 @@ weatherreporter generate tomorrow --out ./tomorrow.md
weatherreporter run evening
```
For the 3-Day Outlook:
```sh
weatherreporter generate three-day --out ./three-day.md
```
## Command Overview
```text
@@ -39,12 +46,14 @@ weatherreporter run morning
weatherreporter run evening
```
`generate daily` and `generate tomorrow` write a briefing snapshot, prompt input
data package, render preflight output, Markdown report, and metadata file under
the configured workspace. `run evening` generates the Tomorrow Planning Brief.
Other `generate` commands resolve one report request and stop before report
generation. Other `run` commands resolve a scheduled batch request and stop
before execution.
`generate daily`, `generate tomorrow`, and `generate three-day` write a briefing
snapshot, prompt input data package, render preflight output, Markdown report,
and metadata file under the configured workspace. `run evening` generates the
Tomorrow Planning Brief. `run morning` can generate Daily Today and the 3-Day
Outlook when the resolved batch contains only implemented report types; when
Weekend Outlook is part of the resolved batch, execution stops at the current
not-implemented boundary. Other `generate` commands resolve one report request
and stop before report generation.
## Flags
@@ -52,7 +61,7 @@ before execution.
- `--config PATH`: load configuration from `PATH` instead of `/usr/local/etc/weatherreporter/config.yml`.
- `--units VALUE`: override configured Weather API units.
- `--tz NAME`: override configured Weather API timezone.
- `--out PATH`: optional Markdown report copy for `generate daily` and `generate tomorrow`; reserved for later generated report output on other `generate` commands.
- `--out PATH`: optional Markdown report copy for `generate daily`, `generate tomorrow`, and `generate three-day`; reserved for later generated report output on other `generate` commands.
- `--date YYYY-MM-DD`: optional date for `generate daily`; defaults to the current local date in the configured timezone.
- `--start TIME`: required start time for `generate storm`.
- `--end TIME`: required end time for `generate storm`.

14
docs/internal/briefing.md
View File

@@ -6,7 +6,7 @@ This document describes the implemented briefing package boundary.
`internal/briefing` builds structured report-specific briefing packages from
forecast summaries and report metadata. The package currently implements Daily
Today and Daily Tomorrow briefing content.
Today, Daily Tomorrow, and 3-Day Outlook briefing content.
## Inputs and Outputs
@@ -14,12 +14,13 @@ Inputs:
- resolved report definition and valid period
- forecast bundle
- derived daily forecast summary
- derived forecast summary or summaries
- configured units and timezone
Output:
- `briefing.Package` JSON containing common metadata and Daily briefing content
- `briefing.Package` JSON containing common metadata and report-specific
briefing content
## Boundaries
@@ -37,12 +38,18 @@ Output:
story context when available.
- Daily Tomorrow also includes planning inputs for morning readiness,
commute/school/workday concerns, and what may change overnight.
- 3-Day content includes one summary per local day or partial day, with overall
character, temperature range, precipitation, wind, risk, outdoor-window, and
alert inputs, plus broader discussion and weather-story context when
available.
- Briefing JSON is written atomically by `briefing.Save`.
## Failure Behavior
- Daily briefing construction requires a Daily report definition and a derived
daily forecast summary.
- 3-Day briefing construction requires a 3-Day report definition and at least
one derived daily summary in the outlook period.
- Save failures include path and operation context.
## Tests
@@ -50,6 +57,7 @@ Output:
Inspect:
- `internal/briefing/daily_test.go`
- `internal/briefing/three_day_test.go`
- `internal/app/app_test.go`
- `internal/cli/root_test.go`

13
docs/internal/changes.md
View File

@@ -11,8 +11,8 @@ produces compact change records for prompt input data packages.
Inputs:
- prior Daily briefing package
- current Daily briefing package
- prior briefing package
- current briefing package
- configured Recent Changes thresholds
Output:
@@ -37,7 +37,7 @@ The app maps these config fields into comparison thresholds:
## Behavior
Daily comparison currently detects:
Daily and 3-Day comparison currently detect:
- temperature changes crossing configured thresholds
- precipitation probability and timing changes
@@ -47,17 +47,20 @@ Daily comparison currently detects:
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.
same-valid-date comparison through the report registry. 3-Day Outlook compares
with prior 3-Day Outlook snapshots for the same valid local date.
## Failure Behavior
Daily comparison requires both inputs to contain Daily briefing content.
Daily comparison requires both inputs to contain Daily briefing content. 3-Day
comparison requires both inputs to contain 3-Day briefing content.
## Tests
Inspect:
- `internal/changes/daily_test.go`
- `internal/changes/three_day_test.go`
- `internal/app/app_test.go`
## Invariants

9
docs/internal/forecast-derivation.md
View File

@@ -6,8 +6,8 @@ boundary.
## Purpose
`internal/forecast` converts a normalized forecast bundle into inspectable
daily daypart summaries. These summaries are structured data for later briefing
builders; they are not rendered report text.
daily and multi-day daypart summaries. These summaries are structured data for
later briefing builders; they are not rendered report text.
## Inputs and Outputs
@@ -15,6 +15,7 @@ Inputs:
- `forecast.Bundle`
- local date and timezone
- report period, for multi-day summaries
- configured daypart definitions with `HH:MM` start and end values
Output:
@@ -22,6 +23,8 @@ Output:
- `forecast.DailySummary` with a civil-day period, daypart summaries, selected
narrative periods, alert overlaps, discussion context, source warnings, and
source provenance.
- `forecast.BuildPeriodDailySummaries` output with one clipped daily summary
for each local day or partial day in a report period.
## Boundaries
@@ -41,6 +44,8 @@ Output:
- Alerts are selected by overlap with the daily period and each daypart.
- Narrative periods and discussion context are selected as broader source
context for later briefing builders.
- Multi-day period summaries clip the first and last local days to the resolved
report period before selecting hourly periods and alerts.
## Failure Behavior

2
docs/internal/prompt-input.md
View File

@@ -11,7 +11,7 @@ This document describes the implemented prompt input package boundary.
Input:
- `briefing.Package`
- `briefing.Package` containing Daily-family or 3-Day Outlook content
Output:

19
docs/internal/state.md
View File

@@ -5,7 +5,7 @@ This document describes the implemented filesystem state boundary.
## Purpose
`internal/state` owns durable artifact paths, atomic JSON writes, metadata, and
prior Daily snapshot lookup.
prior comparable snapshot lookup.
## Inputs and Outputs
@@ -25,8 +25,8 @@ Outputs:
- render preflight JSON
- Markdown report path
- metadata JSON
- prior Daily snapshot metadata when available
- prior Daily briefing package when loaded by path
- prior comparable snapshot metadata when available
- prior briefing package when loaded by path
## Boundaries
@@ -48,12 +48,13 @@ Workspace subdirectories must be relative paths that stay under
## State Behavior
Managed artifact names use RunID, which is generated from report generation time
and report ID. Daily metadata is stored beside Daily briefing snapshots by valid
local date. Prior Daily snapshot lookup reads metadata for the same valid local
date and returns the latest earlier compatible Daily Today or Daily Tomorrow
run. The store can load a briefing snapshot by path for structured comparison.
The store prepares the managed Markdown report path before `scriptorium run`
writes it.
and report ID. Metadata is stored beside briefing snapshots by report group and
valid local date. Prior snapshot lookup reads metadata for the same valid local
date and returns the latest earlier compatible run. Daily Today and Daily
Tomorrow are compatible with each other; 3-Day Outlook is compatible with prior
3-Day Outlook snapshots. The store can load a briefing snapshot by path for
structured comparison. The store prepares the managed Markdown report path
before `scriptorium run` writes it.
## Failure Behavior

32
docs/operations.md
View File

@@ -2,18 +2,21 @@
## Normal Workflow
The implemented Daily-family generation workflows are:
The implemented generation workflows are:
```text
weatherreporter generate daily --date 2026-05-29
weatherreporter generate tomorrow
weatherreporter generate three-day
weatherreporter run evening
```
These commands fetch weather data, build a Daily briefing for the resolved
valid date, build the prompt input data package, run `scriptorium render`, run
These commands fetch weather data, build a briefing for the resolved valid
period, build the prompt input data package, run `scriptorium render`, run
`scriptorium run`, and write inspectable artifacts under the configured
workspace. The evening run resolves only the Tomorrow Planning Brief.
workspace. The evening run resolves only the Tomorrow Planning Brief. The
morning run can generate Daily Today and the 3-Day Outlook when the resolved
batch does not include an unsupported report type.
## Filesystem Layout
@@ -26,22 +29,34 @@ workspace/
YYYY-MM-DD/
<run_id>.briefing.json
<run_id>.metadata.json
three-day/
YYYY-MM-DD/
<run_id>.briefing.json
<run_id>.metadata.json
data-packages/
daily/
YYYY-MM-DD/
<run_id>.data_package.json
three-day/
YYYY-MM-DD/
<run_id>.data_package.json
preflight/
daily/
YYYY-MM-DD/
<run_id>.render.json
three-day/
YYYY-MM-DD/
<run_id>.render.json
reports/
daily/
<run_id>.md
three-day/
<run_id>.md
```
The Markdown report is written to a RunID-managed report path. When `--out` is
provided to `generate daily` or `generate tomorrow`, the managed report is also
copied to that path.
provided to `generate daily`, `generate tomorrow`, or `generate three-day`, the
managed report is also copied to that path.
## Run Identifiers
@@ -56,7 +71,7 @@ date do not overwrite each other.
## Metadata
Each Daily generation writes metadata that links:
Each generated report writes metadata that links:
- RunID
- report ID and prompt ID
@@ -75,6 +90,9 @@ data package. Daily Today and Daily Tomorrow can compare with each other when
they cover the same valid local date. Meaningful changes are included under
`recentChanges.items`.
3-Day Outlook generation compares against a prior compatible 3-Day briefing
snapshot for the same valid local date when one exists.
When no prior comparable snapshot exists, or no configured threshold is crossed,
the Recent Changes list is empty.