From 7cbc59d8a7cfad69892ae602ab08aab7eeac4f69 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 15 Jun 2026 13:00:59 +0000 Subject: [PATCH] Clarify future roadmap documentation --- docs/roadmap/future.md | 157 +++++++++++++++++++---------------------- 1 file changed, 73 insertions(+), 84 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 49888e9..3d6d9af 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -5,18 +5,22 @@ documented outside `docs/roadmap/`. ## Automatic Storm Monitoring -Manual Storm Report generation is implemented through -`weatherreporter generate storm --start TIME --end TIME`. Automatic storm-event -evaluation remains deferred. +Manual Storm Report generation is available through: -Proposed direction: +```sh +weatherreporter generate storm --start TIME --end TIME +``` -1. detect candidate events deterministically from alerts, forecast discussion, - weather story context, hourly thresholds, and material forecast changes; -2. evaluate candidates through Scriptorium or another narrow evaluator adapter; -3. persist storm lifecycle state; -4. generate or update Storm Reports only when a meaningful event is present; -5. suppress ordinary low-impact thunder or rain chances. +Automatic storm-event evaluation is not implemented. + +Possible direction: + +1. Detect candidate storm events from alerts, forecast discussion, weather + story context, hourly thresholds, and material forecast changes. +2. Evaluate candidates through Scriptorium or another narrow evaluator adapter. +3. Persist storm lifecycle state. +4. Generate or update Storm Reports only when a meaningful event is present. +5. Suppress ordinary low-impact thunder or rain chances. Possible lifecycle states: @@ -27,41 +31,41 @@ Possible lifecycle states: - `deescalating` - `resolved` -Acceptance criteria before implementation: +Before implementation, the design must preserve scheduled report behavior, +manual Storm Report generation, inspectable evaluator failures, and fixture +coverage for deterministic candidate detection. -- scheduled reports and manual Storm Reports remain stable; -- candidate detection has fixture coverage; -- evaluator failures are inspectable and do not create noisy report output; -- manual Storm Report generation remains available. - -## Future Report Types And Modules - -The module-based prompt package architecture is implemented. Future work should -add only modules backed by implemented upstream facts and clear report needs. +## Future Report Types Possible future report types: -- another short-fuse planning report distinct from the implemented Hourly - Report, if a separate product is needed; -- event-specific reports with stable event IDs; -- storm review or yesterday-style reports using historical observations; +- a short-fuse planning report distinct from the implemented Hourly Report, if + a separate product is needed +- event-specific reports with stable event IDs +- storm review or yesterday-style reports using historical observations - archive-focused report variants if generated report history becomes a - first-class product. + first-class product + +New reports should keep report identity, prompt IDs, templates, valid-period +resolution, artifact grouping, batch output names, and comparison policy inside +`internal/report`. + +## Future Modules Possible future modules: -- `hourly_table` for compact valid-period hourly facts; +- `hourly_table` for compact valid-period hourly facts - `forecast_delta` if a separate stanza is useful beyond current Recent - Changes; + Changes - `weekend_planning` if weekend-specific planning guidance needs a dedicated - deterministic stanza; + deterministic stanza - `storm_window_summary` if manual or automatic Storm Reports need a dedicated - prompt-facing storm-window module; + prompt-facing storm-window module - separate AFD section aliases, such as `afd_key_messages`, `afd_short_term_text`, and `afd_long_term_text`, if separate stanzas prove - more useful than `area_forecast_discussion.options.sections`; + more useful than `area_forecast_discussion.options.sections` - SPC, radar, QPF, snow/rain total, or historical-observation modules once - upstream sources and report requirements exist. + upstream sources and report requirements exist QPF fields such as `measurable_qpf_total_in` and `max_hourly_qpf_in` should remain omitted until a real upstream quantitative precipitation source is @@ -69,76 +73,61 @@ represented in `CollectedFacts`. Future module work should preserve these boundaries: -- collect upstream facts once per report run; -- keep upstream fetching out of modules; -- keep broad reusable calculations in `DerivedFacts`; -- keep prompt-facing field shape inside module builders; -- use typed options for configurable module behavior; -- keep module snapshots structured and deterministic for Recent Changes. +- collect upstream facts once per report run +- keep upstream fetching out of modules +- keep broad reusable calculations in `DerivedFacts` +- keep prompt-facing field shape inside module builders +- use typed options for configurable module behavior +- keep module snapshots structured and deterministic for Recent Changes ## Distributor Notification Enhancements -Distributor notification currently uploads one managed Markdown report per -successful generated report through the configured HTTP upload pipeline. +Distributor notification uploads one managed Markdown report per successful +generated report through the configured HTTP upload pipeline. The following +enhancements are not implemented: -These enhancements are not current behavior: +- `failure_policy: warn` +- uploading metadata, module snapshots, data packages, or preflight artifacts +- durable upload retry queues +- distributor-specific CLI flags +- distributor workspace scanning +- destination routing, Markdown-to-HTML transformation, public URLs, or nginx + layout inside weatherreporter -- `failure_policy: warn`; -- uploading metadata, module snapshots, data packages, or preflight artifacts; -- durable upload retry queues; -- distributor-specific CLI flags; -- making distributor scan the weatherreporter workspace; -- handling destination routing, Markdown-to-HTML transformation, public URLs, - or nginx layout inside weatherreporter. - -Any distributor enhancement should preserve the existing adapter boundary: +Any distributor enhancement should preserve the adapter boundary: weatherreporter selects explicit generated files and submits source bundles, while distributor owns destination routing and publication behavior. ## Alternate Runtime Integrations -These ideas are not current behavior: +These ideas are not implemented: -- native LLM client inside `weatherreporter`; -- database-backed state; -- public HTTP API; -- multi-location selection; -- daemon mode; -- multi-user authorization; -- plugin system; -- dynamic module loading; -- user-defined module code; -- YAML-defined module schemas; -- module-owned Weather API fetching. +- native LLM client inside `weatherreporter` +- database-backed state +- public HTTP API +- multi-location selection +- daemon mode +- multi-user authorization +- plugin system +- dynamic module loading +- user-defined module code +- YAML-defined module schemas +- module-owned Weather API fetching Each item needs its own design note before implementation. Non-roadmap docs must not describe these as available behavior. -## Cleanup Refactors +## Deferred Refactors -The initial cleanup pass intentionally left these refactors out because the -current implementation does not yet make them worth the added abstraction. +These refactors should remain deferred until new requirements or recurring +maintenance costs make the added abstraction worthwhile: -Revisit these only when new source types, report types, operational -requirements, or recurring maintenance costs make the duplication materially -more expensive: - -- Broad briefing weather-signal consolidation: consider when multiple module - builders repeatedly derive the same weather signals and tests begin to need - coordinated fixture updates. -- Generic workflow engine: defer unless generation, inspection, recovery, or - future background workflows gain enough shared step semantics to justify a - declared execution model. -- Cobra migration: defer while the standard-library CLI remains small, - explicit, and covered by parser tests. -- Manifest, resume, or progress system: defer until operators need resumable - runs, checkpoint recovery, or richer audit trails than the current durable - artifacts and metadata provide. -- Global test helper package: defer while package-local helpers keep tests - clear; revisit only if setup duplication starts to hide behavior. -- Logging subsystem: defer until there are recurring operator diagnostics that - cannot be handled with current errors, metadata, inspection commands, and - artifact output. +- broad briefing weather-signal consolidation +- generic workflow engine +- Cobra migration +- manifest, resume, or progress system +- global test helper package +- logging subsystem Any future implementation should preserve the existing public CLI, artifact paths, report identities, module boundaries, and adapter boundaries unless a