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

Document daily report operations and templates

Browse Source
This commit is contained in:
Eric Rakestraw
2026-06-15 16:54:41 +00:00
parent a515b7e7d9
commit 88004a1827
8 changed files with 67 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/cli.md
View File

@@ -44,10 +44,11 @@ notification uses the managed report path, not the extra copy. `generate daily`,
`generate today`, `generate tomorrow`, and `generate hourly` write managed
generated-text artifacts, validate structured text from Scriptorium, and render
the managed Markdown report from embedded templates. `generate daily` requires
`--date YYYY-MM-DD` for the selected local civil day. `generate hourly` covers
the next six hours in the effective report timezone and does not accept date or
event window flags. `generate storm` requires explicit event-window bounds with
`--start` and `--end`.
`--date YYYY-MM-DD` for the selected local civil day; omitting `--date` is a
command error and stops before weather data is fetched. `generate hourly`
covers the next six hours in the effective report timezone and does not accept
date or event window flags. `generate storm` requires explicit event-window
bounds with `--start` and `--end`.
`run morning` generates Today Report and the 3-Day Outlook, plus Weekend Outlook
except on Sunday. `run evening` generates the Tomorrow Report. Batch

1
docs/config.md
View File

@@ -211,6 +211,7 @@ reports:
sections:
- short_term
- spc_convective_discussion
- daily_planning
- hourly_forecast
today:
deterministic_modules:

18
docs/internal/app-orchestration.md
View File

@@ -135,14 +135,16 @@ failure context.
## Batch Workflow
`run morning` resolves Today Report, 3-Day Outlook, and Weekend Outlook except
on Sunday. `run evening` resolves Tomorrow Report. Batch output copy names come
from report definitions. Batch generation continues independent reports after a
failure, records each result, writes compact status lines to stderr, emits a
JSON summary to stdout, and returns an aggregate error when any report failed.
When notification is enabled, each successfully generated report is notified
independently. Notification failure marks that report failed, records
notification fields in the batch result, and does not stop later reports.
`--out-dir` copies are never used as notification source files.
on Sunday. `run evening` resolves Tomorrow Report. Daily Report is generated
only through `generate daily --date YYYY-MM-DD`; it is not part of scheduled
batches. Batch output copy names come from report definitions. Batch generation
continues independent reports after a failure, records each result, writes
compact status lines to stderr, emits a JSON summary to stdout, and returns an
aggregate error when any report failed. When notification is enabled, each
successfully generated report is notified independently. Notification failure
marks that report failed, records notification fields in the batch result, and
does not stop later reports. `--out-dir` copies are never used as notification
source files.
## Inspection Workflow

2
docs/internal/generatedtext.md
View File

@@ -37,7 +37,7 @@ Outputs:
The Daily generated text JSON accepts the same public fields and validation
rules as Tomorrow. Its catalog entry is selected through schema ID `daily` and
template ID `daily`.
template ID `daily`, with prompt ID `weather.daily_generated_text`.
```json
{

8
docs/operations.md
View File

@@ -68,6 +68,10 @@ workspace/
YYYY-MM-DD/
<run_id>.modules.json
<run_id>.metadata.json
<run_id>.generated_text.raw.json
<run_id>.generated_text.run.json
<run_id>.generated_text.json
<run_id>.render_context.json
today/
YYYY-MM-DD/
<run_id>.modules.json
@@ -238,6 +242,8 @@ The default idempotency key appends RunID to the rendered bundle ID so each
report generation has a distinct retry identity. The default bundle path uses
the valid-period start date, artifact group, and RunID. Distributor owns
destination merge, retention, and derived snapshot behavior such as `latest`.
For Daily, the default report ID and artifact group values are both `daily`,
and the default output filename value is `daily.md`.
For Today, the default report ID and artifact group values are both `today`,
and the batch output filename value is `today.md`.
@@ -311,7 +317,7 @@ A failed generation run may still leave useful artifacts:
preflight JSON and metadata are written for inspection.
- If `scriptorium run` exits nonzero after writing a report, the managed report
and metadata remain available.
- Generated-text failures for Today, Tomorrow, and Hourly reports preserve
- Generated-text failures for Daily, Today, Tomorrow, and Hourly reports preserve
available intermediate artifacts, such as the structured run result, raw
generated-text JSON, validated generated text, and render context. Metadata
links those paths when it can be safely written.

44
docs/templates.md
View File

@@ -8,14 +8,15 @@ especially generated-text-template reports.
Templates are Go `text/template` files. The current implemented templates are:
- `internal/reporttemplate/templates/daily.md.tmpl`
- `internal/reporttemplate/templates/today.md.tmpl`
- `internal/reporttemplate/templates/tomorrow.md.tmpl`
- `internal/reporttemplate/templates/hourly.md.tmpl`
Templates are rendered from structured contexts such as `TodayRenderContext`,
`TomorrowRenderContext`, and `HourlyRenderContext`. Weather data collection,
derivation, module execution, generated text validation, and artifact paths are
handled before template rendering.
Templates are rendered from structured contexts such as `DailyRenderContext`,
`TodayRenderContext`, `TomorrowRenderContext`, and `HourlyRenderContext`.
Weather data collection, derivation, module execution, generated text
validation, and artifact paths are handled before template rendering.
## Editing Rules
@@ -115,6 +116,37 @@ Prefer `.Modules.Dayparts` over ranging through
`.Modules.DerivedDaypartSummaries`; it follows configured daypart order and
falls back to sorted keys for any unmatched entries.
## Daily Context
The Daily template receives the same five top-level values as Tomorrow, using
`DailyReportContext`, `Daily`, and `DailyTemplateModules`.
Daily report metadata includes `.Report.Title`, `.Report.ForecastDate`,
`.Report.ForecastDateLabel`, `.Report.ForecastDayName`,
`.Report.GeneratedAt`, `.Report.GeneratedAtLabel`, `.Report.ValidPeriod`, and
`.Report.Timezone`.
Daily generated text uses `.GeneratedText.Summary`,
`.GeneratedText.ForecastDiscussion`, `.GeneratedText.PrecipitationTiming`, and
`.GeneratedText.Confidence`. Forecast discussion is a slice of paragraphs and
should be rendered with `range`.
Daily uses template ID `daily`, generated-text schema ID `daily`, and prompt
source `internal/reporttemplate/prompts/daily.generated_text.md`.
Daily modules include the Hourly module fields plus:
| Variable | Type | Description |
| --- | --- | --- |
| `.Modules.DerivedDailySummary` | *briefing.DerivedDailySummaryModule | Daily summary facts for the forecast date. |
| `.Modules.DerivedDaypartSummaries` | *map[string]briefing.DerivedDaypartSummaryModule | Raw daypart summary map, when direct keyed access is needed. |
| `.Modules.Dayparts` | []generatedtext.DailyDaypartContext | Ordered daypart summaries for deterministic template rendering. |
| `.Modules.DailyPlanning` | *briefing.DailyPlanningModule | Planning facts for the selected local civil day. |
Prefer `.Modules.Dayparts` over ranging through
`.Modules.DerivedDaypartSummaries`; it follows configured daypart order and
falls back to sorted keys for any unmatched entries.
## Today Context
The Today template receives the same five top-level values as Tomorrow, using
@@ -328,6 +360,6 @@ go run ./cmd/weatherreporter --help
git diff --check
```
Template render tests currently exercise the hourly template through
`internal/generatedtext/render_context_test.go` and
Template render tests exercise the Daily, Today, Tomorrow, and Hourly
templates through `internal/generatedtext/render_context_test.go` and
`internal/reporttemplate/reporttemplate_test.go`.

8
docs/troubleshooting.md
View File

@@ -187,8 +187,8 @@ Relevant docs: [Operations guide](operations.md),
## Generated Text Validation Fails
Symptom: Today, Tomorrow, or Hourly generation fails with generated-text decode,
unknown-field, required-field, or multiple-JSON-values context.
Symptom: Daily, Today, Tomorrow, or Hourly generation fails with generated-text
decode, unknown-field, required-field, or multiple-JSON-values context.
Likely cause: Scriptorium wrote structured JSON that does not match the
GeneratedText contract for the selected report.
@@ -210,8 +210,8 @@ Relevant docs: [Operations guide](operations.md),
## Template Rendering Fails
Symptom: Today, Tomorrow, or Hourly generation fails with report template parsing or
execution context after generated text validation succeeds.
Symptom: Daily, Today, Tomorrow, or Hourly generation fails with report template
parsing or execution context after generated text validation succeeds.
Likely cause: an embedded template references a missing context field or
receives a value shape that does not match its typed render context.

1
examples/config.yml
View File

@@ -88,6 +88,7 @@ reports:
- spc_convective_discussion
- weather_story
- outdoor_windows
- daily_planning
- hourly_forecast
today:
deterministic_modules: