From 7efd8b58559de45f69d83a7bb8b16684d0bf2e2a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 15 Jun 2026 13:07:40 +0000 Subject: [PATCH] Add today report roadmap --- docs/roadmap/today.md | 261 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 docs/roadmap/today.md diff --git a/docs/roadmap/today.md b/docs/roadmap/today.md new file mode 100644 index 0000000..840cc72 --- /dev/null +++ b/docs/roadmap/today.md @@ -0,0 +1,261 @@ +# Today Report Roadmap + +## Purpose + +This roadmap defines the work needed to add a new `today` report type. The +report is not implemented. Current report behavior is documented outside +`docs/roadmap/`. + +## Intent + +Today should be an independent generated-text-template report focused on the +current local civil day. It should mirror the implemented Tomorrow Report +structure, but its valid period, identity, prompt, template, schema, workspace +paths, and distributor identity should use `today`. + +Today should not replace the existing Daily Today report in the same change. +Daily Today currently remains the direct-Markdown `daily` command and report ID +`daily_today`. The Today report should be added as a separate product so the +project can compare the generated-text-template version with the existing +direct-Markdown daily report before deciding whether to retire or rename either +one. + +## Target Report Shape + +Today should render from deterministic current-day facts plus structured prose +from Scriptorium: + +```markdown +# Today's Weather + +**Forecast date:** Friday, May 29, 2026 +**Updated:** Friday, May 29, 2026 at 8:30 AM + + + +## Daypart Forecast + +- **Morning:** +- **Midday:** +- **Afternoon:** +- **Evening:** + +## Precipitation Timing + +- **10:00 AM** to **1:00 PM**: Precipitation is expected during this period. + The peak precipitation chance is 70% at 11:00 AM. +- + +## Forecast Discussion + + +``` + +The precipitation section should render only when precipitation windows exist +for the current-day valid period. The deterministic daypart forecast should +follow the same module-driven presentation approach used by Tomorrow. + +## Report Identity + +Add a report definition with: + +- report ID: `today` +- public generate command: `today` +- prompt ID: `weather.today_generated_text` +- generation mode: `generated_text_template` +- template ID: `today` +- generated-text schema ID: `today` +- artifact group: `today` +- batch output name: `today.md` +- prior compatibility: Today Report only +- comparison strategy: same valid date +- valid period: current local civil day in the effective report timezone + +Do not change existing `daily`, `daily_today`, or morning batch behavior in the +same implementation unless a separate roadmap explicitly calls for that change. + +## GeneratedText Contract + +Today should use the same structured prose shape as Tomorrow: + +```json +{ + "summary": "string", + "forecast_discussion": ["string"], + "precipitation_timing": "string", + "confidence": "string" +} +``` + +Required: + +- `summary` +- `forecast_discussion` + +Optional: + +- `precipitation_timing` +- `confidence` + +Validation should match Tomorrow semantics: + +- reject malformed JSON and unknown fields +- reject trailing JSON values +- trim `summary`, `precipitation_timing`, and `confidence` +- trim each `forecast_discussion` paragraph +- drop blank discussion paragraphs +- require at least one nonblank discussion paragraph +- return canonical normalized JSON with the same public field names + +## Template Context + +Add dedicated Today types under `internal/generatedtext`, rather than reusing +Tomorrow types directly. The shape should mirror Tomorrow so template behavior +stays explicit and testable: + +```go +type TodayRenderContext struct { + Report TodayReportContext + GeneratedText Today + Modules TodayTemplateModules + Collected facts.CollectedFacts + Derived facts.DerivedFacts +} +``` + +`TodayReportContext` should include: + +- `Title`, for example `Today's Weather` +- `ForecastDate` +- `ForecastDateLabel`, for example `Friday, May 29, 2026` +- `ForecastDayName`, for example `Friday` +- `GeneratedAt` +- `GeneratedAtLabel` +- `ValidPeriod` +- `Timezone` + +`TodayTemplateModules` should expose the same categories the Today template +needs: + +- `Metadata` +- `CurrentConditions` +- `HourlyForecast` +- `DerivedDailySummary` +- `DerivedDaypartSummaries` +- ordered daypart rows +- `PrecipTiming` +- `AlertDigest` +- `SPCConvectiveOutlooks` +- `AreaForecastDiscussion` +- `SPCConvectiveDiscussion` +- `WeatherStory` + +Add `TodayPlanning` only if deterministic today-specific planning facts are +introduced. Do not reuse `TomorrowPlanning` for Today. + +## Module Composition + +The default module composition should mirror Tomorrow where the same facts are +useful for the current-day report: + +- `metadata` +- `current_conditions` +- `derived_daily_summary` +- `derived_daypart_summaries` +- `precip_timing` +- `alert_digest` +- `spc_convective_outlooks` +- `area_forecast_discussion` +- `spc_convective_discussion` +- `weather_story` +- `hourly_forecast` + +Keep module outputs deterministic and prompt-facing. Do not add prose-only Go +fields unless the template needs a structured fact that cannot be expressed from +existing module data. + +## Implementation Plan + +1. Add Today report identity. + - Add `report.Today`. + - Add command-name and config-key support for `today`. + - Add a report definition with generated-text-template identity fields. + - Add current-local-day valid-period resolution. + - Add report tests for ID, prompt ID, artifact group, command mapping, + config key mapping, and valid period. + +2. Add Today generated-text validation and schema. + - Add `generatedtext.Today`. + - Add `ValidateToday`. + - Add `today.generated_text.schema.json`. + - Add generated-text validation tests matching Tomorrow coverage. + +3. Add Today template and render context. + - Add `today.md.tmpl`. + - Add `TodayRenderContext`, `TodayReportContext`, and + `TodayTemplateModules`. + - Add `BuildTodayRenderContext`. + - Reuse the internal snapshot lookup helper for module extraction. + - Add render-context and template tests for populated and omitted optional + modules. + +4. Register Today in the generated-text catalog and embedded asset lookups. + - Add a generated-text catalog entry. + - Add reporttemplate template/schema map entries. + - Extend catalog completeness tests. + - Add unsupported schema/template combination coverage if needed. + +5. Integrate app and CLI workflows. + - Ensure `weatherreporter generate today` resolves and runs through the + generated-text-template workflow. + - Persist raw generated text, structured run result, normalized generated + text, render context, Markdown report, metadata, and optional output copy. + - Ensure distributor notification uses the managed Today Markdown report + path and Today template values. + +6. Update current-behavior docs after implementation. + - Update `docs/cli.md`, `docs/config.md`, `docs/operations.md`, + `docs/templates.md`, `docs/internal/report-registry.md`, + `docs/internal/generatedtext.md`, `docs/internal/reporttemplate.md`, + `docs/internal/app-orchestration.md`, and maintained examples as needed. + - Keep any unresolved Daily Today replacement decision only in roadmap docs. + +## Test Plan + +Add or update tests for: + +- report registry membership and command/config-key resolution +- current-day valid period in the configured timezone +- generated-text unknown fields, trailing JSON, missing required fields, blank + fields, paragraph trimming, and canonical output +- generated-text catalog completeness +- template/schema asset lookup +- render context labels, module extraction, nil optional modules, and daypart + ordering +- app workflow artifacts for `generate today` +- optional `--out` copy behavior +- distributor template values and managed report notification source +- CLI parser support for `generate today` +- config report module overrides for `reports.today` + +Suggested validation: + +```sh +go test ./internal/report ./internal/generatedtext ./internal/reporttemplate +go test ./internal/app ./internal/cli ./internal/config +go test ./... +go run ./cmd/weatherreporter --help +git diff --check +``` + +## Open Decisions + +- Whether Today should eventually replace the existing Daily Today report. +- Whether morning batch should include Today, Daily Today, or both. +- Whether Today needs a dedicated deterministic planning module. +- Whether the public `daily` command should remain direct Markdown after Today + exists. + +Do not resolve these decisions implicitly while adding the initial `today` +report. Keep the first implementation narrowly focused on a separate +current-day generated-text-template report.