Add staged implementation plan for the new today report type
This commit is contained in:
@@ -2,23 +2,49 @@
|
||||
|
||||
## 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/`.
|
||||
This roadmap defines the target state and implementation work needed to add a
|
||||
new independent generated-text-template `today` report.
|
||||
|
||||
The report is not implemented yet. Current report behavior remains 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`.
|
||||
paths, distributor identity, and deterministic planning module 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.
|
||||
This is a clean, separate report addition:
|
||||
|
||||
- `today` becomes a new canonical current-day generated-text report ID.
|
||||
- The existing `daily_today` report remains independent for now.
|
||||
- The existing public `daily` command remains independent for now.
|
||||
- `weatherreporter generate today` and `weatherreporter generate daily` must
|
||||
not be aliases for each other.
|
||||
- Morning batch should use `today`, not `daily_today`.
|
||||
- New Today artifacts use the `today` artifact group and report ID.
|
||||
- Existing historical `daily_today` workspace artifacts do not need migration.
|
||||
|
||||
The next planned feature will rewrite the `daily` command/report in the same
|
||||
style as Today and Tomorrow. Do not pre-solve that future work in this roadmap.
|
||||
|
||||
## Locked Decisions
|
||||
|
||||
- `today` is independent of `daily_today`.
|
||||
- `generate today` is independent of `generate daily`.
|
||||
- No command compatibility aliases between `today` and `daily`.
|
||||
- No config-key compatibility aliases between `reports.today` and
|
||||
`reports.daily` / `reports.daily_today`.
|
||||
- Morning batch includes `today`.
|
||||
- Morning batch should not include `daily_today` once Today is implemented.
|
||||
- `today` needs its own deterministic planning module analogous to
|
||||
`TomorrowPlanning`.
|
||||
- Add a new public `generate today` command.
|
||||
- Do not reuse the Tomorrow prompt, template, schema, report ID, artifact group,
|
||||
or planning stanza for Today.
|
||||
- Do not attempt to migrate old workspace artifacts.
|
||||
|
||||
## Target Report Shape
|
||||
|
||||
@@ -55,6 +81,8 @@ 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.
|
||||
|
||||
The title should be stable and explicit: `Today's Weather`.
|
||||
|
||||
## Report Identity
|
||||
|
||||
Add a report definition with:
|
||||
@@ -67,12 +95,44 @@ Add a report definition with:
|
||||
- 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
|
||||
- prior compatibility: Today only
|
||||
- comparison strategy: same valid local date
|
||||
- valid period: current local civil day in the effective report timezone,
|
||||
`[00:00, next 00:00)`
|
||||
|
||||
Do not change existing `daily`, `daily_today`, or morning batch behavior in the
|
||||
same implementation unless a separate roadmap explicitly calls for that change.
|
||||
Keep the existing `daily_today` report definition independent unless the future
|
||||
Daily rewrite roadmap removes or replaces it.
|
||||
|
||||
Command and config resolution must remain distinct:
|
||||
|
||||
- `generate today` resolves to report ID `today`.
|
||||
- `generate daily` resolves to the existing daily report ID.
|
||||
- `reports.today` config overrides apply only to report ID `today`.
|
||||
- `reports.daily` and `reports.daily_today` config overrides continue to apply
|
||||
only to the existing daily report while that report exists.
|
||||
|
||||
## Batch Behavior
|
||||
|
||||
Morning batch should include Today in the position currently occupied by Daily
|
||||
Today.
|
||||
|
||||
Target morning order:
|
||||
|
||||
1. `today`
|
||||
2. `three_day`
|
||||
3. `weekend`, when existing weekend rules include it
|
||||
|
||||
Existing Sunday behavior should remain equivalent except with Today replacing
|
||||
Daily Today in the batch: scheduled Sunday morning should include `today` and
|
||||
`three_day`, and should skip `weekend`.
|
||||
|
||||
Evening batch behavior is unchanged and should continue to include `tomorrow`.
|
||||
Hourly remains excluded from scheduled batches unless a later roadmap changes
|
||||
that.
|
||||
|
||||
The existing `daily` command/report may remain available for manual generation,
|
||||
but it is no longer the morning batch current-day product once Today is
|
||||
implemented.
|
||||
|
||||
## GeneratedText Contract
|
||||
|
||||
@@ -107,6 +167,15 @@ Validation should match Tomorrow semantics:
|
||||
- require at least one nonblank discussion paragraph
|
||||
- return canonical normalized JSON with the same public field names
|
||||
|
||||
Add a dedicated prompt asset for the source prompt text if prompt assets are
|
||||
maintained locally:
|
||||
|
||||
- `internal/reporttemplate/prompts/today.generated_text.md`
|
||||
|
||||
Scriptorium registration remains out of band. Weatherreporter should invoke the
|
||||
Today prompt by prompt ID and pass the data package as it does for other
|
||||
generated-text reports.
|
||||
|
||||
## Template Context
|
||||
|
||||
Add dedicated Today types under `internal/generatedtext`, rather than reusing
|
||||
@@ -125,7 +194,7 @@ type TodayRenderContext struct {
|
||||
|
||||
`TodayReportContext` should include:
|
||||
|
||||
- `Title`, for example `Today's Weather`
|
||||
- `Title`, exactly `Today's Weather`
|
||||
- `ForecastDate`
|
||||
- `ForecastDateLabel`, for example `Friday, May 29, 2026`
|
||||
- `ForecastDayName`, for example `Friday`
|
||||
@@ -134,8 +203,7 @@ type TodayRenderContext struct {
|
||||
- `ValidPeriod`
|
||||
- `Timezone`
|
||||
|
||||
`TodayTemplateModules` should expose the same categories the Today template
|
||||
needs:
|
||||
`TodayTemplateModules` should expose the categories the Today template needs:
|
||||
|
||||
- `Metadata`
|
||||
- `CurrentConditions`
|
||||
@@ -149,17 +217,21 @@ needs:
|
||||
- `AreaForecastDiscussion`
|
||||
- `SPCConvectiveDiscussion`
|
||||
- `WeatherStory`
|
||||
- `TodayPlanning`
|
||||
|
||||
Add `TodayPlanning` only if deterministic today-specific planning facts are
|
||||
introduced. Do not reuse `TomorrowPlanning` for Today.
|
||||
Today may share private helper functions with Tomorrow render-context
|
||||
construction when the helper represents identical mechanics, such as snapshot
|
||||
lookup or daypart row ordering. Do not expose Tomorrow-specific types through
|
||||
the Today template context.
|
||||
|
||||
## Module Composition
|
||||
|
||||
The default module composition should mirror Tomorrow where the same facts are
|
||||
useful for the current-day report:
|
||||
useful for the current-day report, with a Today-specific planning module:
|
||||
|
||||
- `metadata`
|
||||
- `current_conditions`
|
||||
- `narrative_forecast`
|
||||
- `derived_daily_summary`
|
||||
- `derived_daypart_summaries`
|
||||
- `precip_timing`
|
||||
@@ -168,71 +240,130 @@ useful for the current-day report:
|
||||
- `area_forecast_discussion`
|
||||
- `spc_convective_discussion`
|
||||
- `weather_story`
|
||||
- `outdoor_windows`
|
||||
- `hourly_forecast`
|
||||
- `today_planning`
|
||||
|
||||
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.
|
||||
|
||||
## Today Planning Module
|
||||
|
||||
Add a Today-specific deterministic planning module:
|
||||
|
||||
- module ID: `today_planning`
|
||||
- stanza name: `today_planning`
|
||||
- options type: `TodayPlanningOptions`
|
||||
- output type: `TodayPlanningModule`
|
||||
- supported report: `today`
|
||||
|
||||
The module should be analogous to `TomorrowPlanning`, but current-day oriented.
|
||||
It should not reuse the public `TomorrowPlanningModule` type or
|
||||
`tomorrow_planning` stanza.
|
||||
|
||||
Recommended initial fields:
|
||||
|
||||
- `morning_readiness`
|
||||
- `commute_school_workday_concerns`
|
||||
- `outdoor_planning`
|
||||
- `late_day_change_watch`
|
||||
|
||||
The exact field names may be adjusted during implementation if tests and docs
|
||||
make a better shape clear, but the module must remain deterministic and
|
||||
current-day specific. Private helper functions may be shared with Tomorrow
|
||||
planning when the underlying logic is truly identical.
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
1. Add Today report identity.
|
||||
- Add `report.Today`.
|
||||
- Add command-name and config-key support for `today`.
|
||||
- Keep the existing `report.DailyToday` active for now.
|
||||
- Add command-name support for `today`.
|
||||
- Do not change the `daily` command mapping in this roadmap.
|
||||
- Add config-key support for `today`.
|
||||
- Do not change `reports.daily` or `reports.daily_today` mapping in this
|
||||
roadmap.
|
||||
- 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.
|
||||
- Add current-local-civil-day valid-period resolution.
|
||||
- Update report tests for ID, prompt ID, artifact group, command mapping,
|
||||
config key mapping, batch order, and valid period.
|
||||
|
||||
2. Add Today generated-text validation and schema.
|
||||
2. Add Today planning module.
|
||||
- Add `module.TodayPlanning`.
|
||||
- Add `TodayPlanningOptions`.
|
||||
- Add `TodayPlanningModule` and builder under `internal/briefing`.
|
||||
- Register it in the default module registry for `report.Today`.
|
||||
- Add tests for output shape, supported report, unsupported reports, and
|
||||
empty/fallback behavior.
|
||||
|
||||
3. 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.
|
||||
4. 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.
|
||||
- Use 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.
|
||||
5. Register Today in generated-text and embedded asset catalogs.
|
||||
- Add a generated-text catalog entry.
|
||||
- Add reporttemplate template/schema map entries.
|
||||
- Add reporttemplate template/schema map entries if the current asset
|
||||
lookup still uses explicit maps.
|
||||
- Extend catalog completeness tests.
|
||||
- Add unsupported schema/template combination coverage if needed.
|
||||
|
||||
5. Integrate app and CLI workflows.
|
||||
6. Integrate app, CLI, config, batches, and distributor workflows.
|
||||
- Ensure `weatherreporter generate today` resolves and runs through the
|
||||
generated-text-template workflow.
|
||||
- Ensure `weatherreporter generate daily` remains the existing daily
|
||||
workflow and does not resolve to Today.
|
||||
- Ensure morning batch uses `today` instead of `daily_today`.
|
||||
- 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.
|
||||
- Ensure report metadata, RunID, artifact paths, data-package paths, batch
|
||||
output names, and distributor template variables use `today`.
|
||||
|
||||
6. Update current-behavior docs after implementation.
|
||||
7. Update implemented documentation after code changes.
|
||||
- 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.
|
||||
`docs/internal/module.md`, `docs/internal/app-orchestration.md`, and
|
||||
maintained examples as needed.
|
||||
- Non-roadmap docs must describe only the implemented Today behavior after
|
||||
the code changes land.
|
||||
- Keep `daily` and `today` documented as distinct commands/reports.
|
||||
|
||||
## Test Plan
|
||||
|
||||
Add or update tests for:
|
||||
|
||||
- report registry membership and command/config-key resolution
|
||||
- report registry membership for both `today` and existing `daily_today`
|
||||
- `today` command-name resolution to `today`
|
||||
- `daily` command-name resolution remaining independent from `today`
|
||||
- config-key resolution for `reports.today`
|
||||
- config-key resolution for `reports.daily` and `reports.daily_today`
|
||||
remaining independent from `reports.today`
|
||||
- morning batch order with `today`, `three_day`, and conditional `weekend`
|
||||
- Sunday morning batch skip behavior with `today`
|
||||
- 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
|
||||
- render context labels, module extraction, nil optional modules, Today
|
||||
planning extraction, and daypart ordering
|
||||
- Today planning module output and supported-report validation
|
||||
- app workflow artifacts for `generate today`
|
||||
- `generate daily` remains separate from `generate today`
|
||||
- optional `--out` copy behavior
|
||||
- distributor template values and managed report notification source
|
||||
- CLI parser support for `generate today`
|
||||
@@ -242,20 +373,52 @@ Suggested validation:
|
||||
|
||||
```sh
|
||||
go test ./internal/report ./internal/generatedtext ./internal/reporttemplate
|
||||
go test ./internal/briefing ./internal/module
|
||||
go test ./internal/app ./internal/cli ./internal/config
|
||||
go test ./...
|
||||
go run ./cmd/weatherreporter --help
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Documentation Updates After Implementation
|
||||
|
||||
Update implemented docs only after the code exists:
|
||||
|
||||
- `docs/cli.md`: document `generate today` and keep `generate daily`
|
||||
documented as a separate existing command.
|
||||
- `docs/config.md`: document `reports.today` module overrides separately from
|
||||
existing daily report overrides.
|
||||
- `docs/operations.md`: document Today artifact paths, morning batch behavior,
|
||||
and distributor upload identity.
|
||||
- `docs/templates.md`: document Today template variables.
|
||||
- `docs/internal/report-registry.md`: document Today report identity and its
|
||||
independence from Daily Today.
|
||||
- `docs/internal/generatedtext.md`: document Today generated-text schema and
|
||||
validation behavior.
|
||||
- `docs/internal/reporttemplate.md`: document Today template assets.
|
||||
- `docs/internal/module.md`: document `today_planning`.
|
||||
- `docs/internal/app-orchestration.md`: document Today workflow only if it
|
||||
differs from the generic generated-text-template flow.
|
||||
|
||||
## Ambiguities Addressed
|
||||
|
||||
- Independence: `today` is separate from `daily_today`; it does not replace the
|
||||
existing report definition in this roadmap.
|
||||
- Command behavior: `generate today` and `generate daily` are not aliases.
|
||||
- Config behavior: `reports.today` is not an alias for `reports.daily` or
|
||||
`reports.daily_today`.
|
||||
- Batch behavior: morning batch includes `today` instead of `daily_today`.
|
||||
- Planning module: Today has its own deterministic planning module.
|
||||
- Artifact identity: new Today artifacts and distributor values use `today`.
|
||||
- Historical artifacts: old `daily_today` workspace files are not migrated.
|
||||
|
||||
## 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.
|
||||
No open decisions remain that block implementation.
|
||||
|
||||
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.
|
||||
Future decisions that should not be resolved in this roadmap:
|
||||
|
||||
- How the future rewritten `daily` command/report should relate to `today`.
|
||||
- Whether the future Daily rewrite removes or retires `daily_today`.
|
||||
- Whether old `daily_today` workspace artifacts should ever receive a migration
|
||||
or inspection compatibility layer.
|
||||
|
||||
Reference in New Issue
Block a user