364 lines
11 KiB
Markdown
364 lines
11 KiB
Markdown
# Near-Term Report Roadmap
|
|
|
|
## Purpose
|
|
|
|
This roadmap defines planned work to add a rolling `near_term` report focused
|
|
on the next several hours. The feature is not implemented yet, so this document
|
|
lives under `docs/roadmap/`.
|
|
|
|
The goal is a frequently generated report that helps readers understand what
|
|
matters in the immediate future: current conditions, hourly evolution,
|
|
precipitation timing, applicable hazards, applicable SPC risk products, and the
|
|
most relevant short-term narrative context.
|
|
|
|
## Target Behavior
|
|
|
|
Add a generated report with:
|
|
|
|
- report ID: `near_term`
|
|
- display name: `Near-Term Report`
|
|
- prompt ID: `weather.near_term_report`
|
|
- artifact group: `near-term`
|
|
- batch output name: `near-term.md`
|
|
- default valid-period length: 6 hours
|
|
- valid period: `[generation_time, generation_time + nearTermHours)`
|
|
|
|
The report should use a package-owned constant for the valid-period length, for
|
|
example:
|
|
|
|
```go
|
|
const nearTermHours = 6
|
|
```
|
|
|
|
Do not make the duration configurable in the first implementation. The constant
|
|
exists so the value can be changed later to 4 or 8 hours without changing
|
|
valid-period logic in multiple places.
|
|
|
|
## Locked Decisions
|
|
|
|
- The report ID is `near_term`.
|
|
- The report is rolling and generation-time anchored, not civil-day anchored.
|
|
- The first implementation covers the next 6 hours through a constant.
|
|
- The report should be generated explicitly by CLI command before deciding
|
|
whether it belongs in scheduled batches.
|
|
- The first implementation should declare `rolling_window` comparison policy
|
|
but should not emit Recent Changes output for `near_term`.
|
|
- Alert and SPC products should be included only when their valid periods
|
|
overlap the resolved near-term report period.
|
|
- SPC discussion text should keep the existing categorical-risk threshold rule
|
|
and should still require overlap with the near-term report period.
|
|
- The AFD stanza should include key messages and short term text by default.
|
|
- Daily-only modules should not be forced into this report.
|
|
|
|
## Report Definition
|
|
|
|
Add a report definition under `internal/report`, preferably in a focused
|
|
`near_term_report.go` file.
|
|
|
|
Definition fields:
|
|
|
|
- `ID`: `NearTerm`
|
|
- `Name`: `Near-Term Report`
|
|
- `PromptID`: `weather.near_term_report`
|
|
- `ComparisonStrategy`: `rolling_window`
|
|
- `ArtifactGroup`: `near-term`
|
|
- `BatchOutputName`: `near-term.md`
|
|
- `Generated`: `true`
|
|
- `CompatiblePriorIDs`: `[]ID{NearTerm}`
|
|
- `Modules`: near-term module list below
|
|
- `resolve`: rolling near-term resolver
|
|
|
|
Valid-period resolver:
|
|
|
|
```go
|
|
func resolveNearTerm(req ResolveRequest) (timeutil.Period, error) {
|
|
localNow := req.Now.In(req.Location)
|
|
return timeutil.Period{
|
|
Start: localNow,
|
|
End: localNow.Add(nearTermHours * time.Hour),
|
|
}, nil
|
|
}
|
|
```
|
|
|
|
The implementation should use idiomatic package-local constants and avoid
|
|
duplicating duration literals in tests or app code.
|
|
|
|
## Default Module Composition
|
|
|
|
Default module order should be:
|
|
|
|
1. `metadata`
|
|
2. `current_conditions`
|
|
3. `hourly_forecast`
|
|
4. `precip_timing`
|
|
5. `alert_digest`
|
|
6. `spc_convective_outlooks`
|
|
7. `area_forecast_discussion`
|
|
8. `spc_convective_discussion`
|
|
9. `weather_story`
|
|
|
|
`area_forecast_discussion` should use options equivalent to:
|
|
|
|
```yaml
|
|
sections:
|
|
- key_messages
|
|
- short_term
|
|
```
|
|
|
|
Do not include these daily/daypart-oriented modules initially:
|
|
|
|
- `derived_daily_summary`
|
|
- `derived_daypart_summaries`
|
|
- `outdoor_windows`
|
|
- `tomorrow_planning`
|
|
|
|
If the report needs deterministic summary facts later, add a purpose-built
|
|
module such as `derived_near_term_summary` rather than stretching daily modules
|
|
into a rolling sub-daily context.
|
|
|
|
## Prompt Package Shape
|
|
|
|
The existing prompt-input category layout should remain unchanged:
|
|
|
|
- `applicable_risk_products`
|
|
- `derived_summaries`
|
|
- `narrative_products`
|
|
- `raw_data`
|
|
|
|
Near-term output is expected to emphasize:
|
|
|
|
- `current_conditions` and `hourly_forecast` under `raw_data`
|
|
- `precip_timing` under `derived_summaries`
|
|
- `alert_digest` and `spc_convective_outlooks` under
|
|
`applicable_risk_products`
|
|
- `area_forecast_discussion`, `spc_convective_discussion`, and
|
|
`weather_story` under `narrative_products`
|
|
|
|
Module interval fields should use the existing prompt-facing
|
|
`period_begins` / `period_ends` convention.
|
|
|
|
## Overlap And Filtering Rules
|
|
|
|
Hourly forecast:
|
|
|
|
- use only hourly periods overlapping the near-term valid period;
|
|
- preserve hourly period order;
|
|
- do not include the full daily forecast.
|
|
|
|
Narrative products:
|
|
|
|
- AFD key messages and short term text may be included because the AFD is an
|
|
official short-term forecast discussion product;
|
|
- narrative forecast periods are not included by default unless a later prompt
|
|
test shows they improve near-term output.
|
|
|
|
Alerts:
|
|
|
|
- include active alert overlaps only when the alert overlaps the near-term
|
|
valid period;
|
|
- if alerts were checked successfully and no alerts overlap, emit checked empty
|
|
alert context through existing module behavior.
|
|
|
|
SPC outlooks:
|
|
|
|
- include only retained outlooks whose valid periods overlap the near-term
|
|
valid period;
|
|
- do not include non-overlapping outlooks even if they are severe;
|
|
- keep current prompt-facing field exclusions for geometry, severity rank,
|
|
expiration time, and source URL.
|
|
|
|
SPC discussion:
|
|
|
|
- include discussion only for SPC days where a retained overlapping categorical
|
|
outlook has severity rank at least `3`;
|
|
- do not include discussion for low-risk, non-categorical-only, or
|
|
non-overlapping outlooks.
|
|
|
|
Weather story:
|
|
|
|
- include when available under current optional-source behavior;
|
|
- do not require the story valid period to exactly match the near-term period
|
|
unless later testing shows stale stories are a problem.
|
|
|
|
## Implementation Stages
|
|
|
|
### Stage 1: Report Registry
|
|
|
|
Goal: add the `near_term` report definition and valid-period resolver.
|
|
|
|
Files to inspect or update:
|
|
|
|
- `internal/report/definition.go`
|
|
- `internal/report/registry.go`
|
|
- `internal/report/period.go`
|
|
- new `internal/report/near_term_report.go`
|
|
- `internal/report/period_test.go`
|
|
- `docs/internal/report-registry.md` after implementation
|
|
|
|
Acceptance criteria:
|
|
|
|
- `report.DefaultRegistry().Lookup(report.NearTerm)` succeeds.
|
|
- `report.Registry.All()` includes the report in a stable order.
|
|
- resolving the report at a fixed generation time produces a half-open
|
|
six-hour period.
|
|
- report metadata and RunID include `near_term`.
|
|
|
|
### Stage 2: Module Compatibility And Defaults
|
|
|
|
Goal: allow existing relevant modules to build for `near_term` and define the
|
|
default near-term composition.
|
|
|
|
Files to inspect or update:
|
|
|
|
- `internal/briefing/modules.go`
|
|
- `internal/report/near_term_report.go`
|
|
- `internal/briefing/*_module_test.go`
|
|
- `internal/module/module_test.go`
|
|
|
|
Acceptance criteria:
|
|
|
|
- all default near-term modules validate and build from appropriate test facts;
|
|
- daily-only modules remain incompatible unless intentionally expanded;
|
|
- `area_forecast_discussion` defaults to key messages and short term only for
|
|
this report.
|
|
|
|
### Stage 3: Derived Facts
|
|
|
|
Goal: make `internal/facts` derive report-period facts for `near_term`.
|
|
|
|
Files to inspect or update:
|
|
|
|
- `internal/facts/facts.go`
|
|
- `internal/facts/facts_test.go`
|
|
- `internal/forecast` selection helpers, if needed
|
|
|
|
Acceptance criteria:
|
|
|
|
- valid-period hourly periods are sliced to the six-hour window;
|
|
- precipitation timing is built from that six-hour hourly slice;
|
|
- alert overlaps use the near-term valid period;
|
|
- SPC outlook and discussion derivation use the near-term valid period;
|
|
- no daily summaries or daypart summaries are required for the default
|
|
near-term module set.
|
|
|
|
### Stage 4: CLI And App Wiring
|
|
|
|
Goal: add explicit generation support without changing existing commands.
|
|
|
|
Files to inspect or update:
|
|
|
|
- `internal/app`
|
|
- `internal/cli`
|
|
- `cmd/weatherreporter/main.go`
|
|
- `docs/cli.md` after implementation
|
|
|
|
Expected command:
|
|
|
|
```bash
|
|
weatherreporter generate near-term [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
|
```
|
|
|
|
Acceptance criteria:
|
|
|
|
- command maps to `report.NearTerm`;
|
|
- no `--date`, `--start`, or `--end` flags are added for this report;
|
|
- existing `generate daily`, `generate tomorrow`, `generate three-day`,
|
|
`generate weekend`, and `generate storm` behavior is unchanged;
|
|
- CLI help lists the new command.
|
|
|
|
### Stage 5: Prompt Input And State Coverage
|
|
|
|
Goal: prove the managed module snapshot and data package contain the intended
|
|
near-term stanzas.
|
|
|
|
Files to inspect or update:
|
|
|
|
- `internal/app/app_test.go`
|
|
- `internal/promptinput`
|
|
- `internal/state`
|
|
|
|
Acceptance criteria:
|
|
|
|
- generated module snapshot includes the near-term default module list in
|
|
order;
|
|
- data package uses existing categories;
|
|
- alert/SPC stanzas are omitted or checked-empty according to current module
|
|
behavior and valid-period overlap;
|
|
- report metadata preserves canonical `valid_period`;
|
|
- module interval labels use `period_begins` and `period_ends`.
|
|
|
|
### Stage 6: Documentation And Examples
|
|
|
|
Goal: document implemented behavior only after the code exists.
|
|
|
|
Files to inspect or update after implementation:
|
|
|
|
- `docs/cli.md`
|
|
- `docs/internal/report-registry.md`
|
|
- `docs/internal/module.md`
|
|
- `docs/internal/facts.md`
|
|
- `docs/internal/briefing.md`
|
|
- `docs/config.md` only if report module overrides need an example update
|
|
- `examples/config.yml` only if it lists report module overrides
|
|
|
|
Acceptance criteria:
|
|
|
|
- non-roadmap docs describe `near_term` only after implementation;
|
|
- future or deferred near-term summary modules remain under roadmap docs;
|
|
- examples, if updated, load through existing config tests.
|
|
|
|
## Test Plan
|
|
|
|
Focused tests:
|
|
|
|
```bash
|
|
go test ./internal/report ./internal/briefing ./internal/facts
|
|
go test ./internal/app ./internal/cli ./internal/promptinput
|
|
```
|
|
|
|
Full validation:
|
|
|
|
```bash
|
|
go test ./...
|
|
go run ./cmd/weatherreporter --help
|
|
git diff --check
|
|
```
|
|
|
|
Important coverage:
|
|
|
|
- six-hour valid-period resolution from a fixed generation time;
|
|
- timezone-aware period start and end;
|
|
- no civil-day truncation;
|
|
- hourly periods selected by overlap with the rolling window;
|
|
- alert overlap filtering;
|
|
- SPC outlook filtering by overlap;
|
|
- SPC discussion filtering by overlap plus categorical severity threshold;
|
|
- AFD key messages and short term included;
|
|
- daily-only modules rejected or absent from default near-term composition;
|
|
- distributor bundle path templates render sensibly for a sub-daily report,
|
|
especially valid start time variables.
|
|
|
|
## Deferred Work
|
|
|
|
Do not include these in the first implementation:
|
|
|
|
- user-configurable near-term duration;
|
|
- adding `near_term` to scheduled morning or evening batches;
|
|
- a dedicated `derived_near_term_summary` module;
|
|
- narrative forecast periods by default;
|
|
- separate AFD section modules;
|
|
- near-term-specific Recent Changes comparison output;
|
|
- CLI flags for custom near-term duration.
|
|
|
|
## Open Questions
|
|
|
|
None block the roadmap.
|
|
|
|
Recommendation: implement the first version as explicit `generate near-term`
|
|
only, with no scheduled batch membership. That keeps the user-visible behavior
|
|
small while the prompt and generated report are tested.
|
|
|
|
Viable alternative: add `near_term` to a frequent scheduled batch immediately.
|
|
That may be useful operationally, but it should wait until the report cadence
|
|
and downstream distributor behavior are clear.
|