weatherreporter/docs/roadmap/near-term.md

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:

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:

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:

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:

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:

go test ./internal/report ./internal/briefing ./internal/facts
go test ./internal/app ./internal/cli ./internal/promptinput

Full validation:

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.