From 3482551360ad87b0112d0b69bdf9c2e02f730907 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 12 Jun 2026 15:17:06 +0000 Subject: [PATCH] Document SPC convective outlook behavior --- docs/integrations/weatherapi.md | 58 +++++++++++++++++++++++++++++++-- docs/internal/briefing.md | 15 +++++++-- docs/internal/facts.md | 10 ++++-- docs/internal/module.md | 26 ++++++++++++++- docs/internal/prompt-input.md | 6 +++- docs/internal/weather-data.md | 8 +++++ 6 files changed, 114 insertions(+), 9 deletions(-) diff --git a/docs/integrations/weatherapi.md b/docs/integrations/weatherapi.md index 4b9a409..71bda36 100644 --- a/docs/integrations/weatherapi.md +++ b/docs/integrations/weatherapi.md @@ -60,6 +60,60 @@ Alerts do not receive `precision` or `tz`. Weather story requests receive only `format=json`. SPC convective outlook requests receive only `format=json` and `tz`; they do not receive `units` or `precision`. +## SPC Convective Outlooks + +The adapter fetches SPC convective outlook data from: + +```text +GET /outlooks/convective?format=json&tz= +``` + +The response uses the standard `data` envelope. `data: null` means no latest +run is available and follows missing-source policy. A non-null object with +empty `outlooks` and `discussions` arrays is accepted as checked empty data. + +Run fields consumed by weatherreporter: + +- `locationId` +- `locationName` +- `asOf` +- `issuedAt` +- `updatedAt` +- `product` +- `outlooks` +- `discussions` + +Outlook fields consumed: + +- `id` +- `provider` +- `product` +- `day` +- `outlookType` +- `label` +- `labelText` +- `forecaster` +- `severityRank` +- `validFrom` +- `validTo` +- `issuedAt` +- `expiresAt` +- `sourceUrl` +- `imageUrl` +- `containsLocation` +- `geometry` + +Discussion fields consumed: + +- `day` +- `headline` +- `summary` +- `discussion` +- `updatedAt` + +GeoJSON `geometry` is decoded into collected weather facts and persisted in +bundle/debug artifacts, but prompt-facing SPC module output omits geometry. + ## Endpoints Used The adapter fetches these endpoints once per bundle: @@ -126,8 +180,8 @@ warnings list. ## Compatibility Assumptions -The adapter expects payload fields compatible with the internal forecast bundle -types in `internal/forecast/bundle.go`, including: +The adapter expects payload fields compatible with the internal weather data +bundle types in `internal/weatherdata/bundle.go`, including: - observation timestamps and observation values - current condition values diff --git a/docs/internal/briefing.md b/docs/internal/briefing.md index 6fda4dd..c0ca214 100644 --- a/docs/internal/briefing.md +++ b/docs/internal/briefing.md @@ -61,6 +61,17 @@ builders run. Configured `location` values are prompt context only; Weather API `area_forecast_discussion` uses optional `sections` configuration to include a subset of discussion fields. +`spc_convective_outlooks` uses collected SPC run metadata and derived +report-period outlooks. It emits `checked: true` for a successfully fetched +empty run, reports `outlook_count`, and includes prompt-facing outlook fields +such as risk label, severity rank, valid times, source URL, image URL, and +whether the outlook contains the configured location. It does not emit GeoJSON +geometry. + +`spc_convective_discussion` uses the same derived report-period outlooks and +discussion records. It is omitted unless at least one retained outlook has +severity rank `3` or higher and matching discussion text exists. + ## External Adapters Used None directly. @@ -91,8 +102,8 @@ return an error for invalid required inputs. - SPC convective outlook output distinguishes checked empty outlook data from missing outlook source data and omits GeoJSON geometry from prompt-facing fields. -- SPC convective discussion output is omitted unless a retained outlook meets - the internal severity threshold and matching discussion text is available. +- SPC convective discussion output is omitted unless a retained outlook has + severity rank `3` or higher and matching discussion text is available. ## Tests diff --git a/docs/internal/facts.md b/docs/internal/facts.md index 99b0426..91d3fe6 100644 --- a/docs/internal/facts.md +++ b/docs/internal/facts.md @@ -21,7 +21,8 @@ Outputs: - `facts.CollectedFacts` with normalized source facts plus separate source provenance and warnings. SPC convective outlook source data is carried - through when present in the bundle. + through when present in the bundle, including upstream geometry and source + provenance. - `facts.DerivedFacts` with valid-period forecast slices, alert overlaps, report-period SPC convective outlooks and discussions, daily summaries, daypart summaries, and Storm Report window summary @@ -33,6 +34,9 @@ Outputs: - SPC convective outlook derivation selects already-collected outlooks whose half-open valid intervals overlap the resolved report period and retains discussions for represented outlook days. +- Derived SPC outlook records preserve the collected outlook fields, including + geometry, for downstream components that need source-level facts. Prompt + modules decide which fields are exposed to Scriptorium. - It does not fetch upstream data, build prompt wording, compare prior snapshots, write workflow state, invoke Scriptorium, or define modules. @@ -75,8 +79,8 @@ Inspect: - Collected facts are built once from a fetched bundle. - Derived facts are scoped to one resolved report. -- SPC convective outlook selection uses the resolved report period, not - server-current active filtering. +- SPC convective outlook selection uses the resolved report period and the + already-collected outlook run. - Source provenance and warnings stay separate from ordinary fact fields. - Prompt-specific wording and one-off presentation decisions stay outside this package. diff --git a/docs/internal/module.md b/docs/internal/module.md index 6dbb9d9..881f1be 100644 --- a/docs/internal/module.md +++ b/docs/internal/module.md @@ -49,7 +49,9 @@ unknown or unimplemented module IDs fail validation instead of being skipped. ## Options -Most modules use an empty options struct. `area_forecast_discussion` accepts: +Most modules use an empty options struct, including +`spc_convective_outlooks` and `spc_convective_discussion`. +`area_forecast_discussion` accepts: ```yaml sections: @@ -63,6 +65,28 @@ An omitted or empty `sections` list includes all available discussion sections. Invalid option shapes fail during config normalization or composition validation. +## SPC Convective Module Outputs + +`spc_convective_outlooks` emits a prompt-facing risk-product stanza with: + +- `checked` +- `as_of` +- `issued_at` +- `location_id` +- `location_name` +- `outlook_count` +- `outlooks` + +Each outlook entry may include `day`, `outlook_type`, `label`, `label_text`, +`severity_rank`, `valid_start`, `valid_end`, `issued_at`, `expires_at`, +`contains_location`, `source_url`, and `image_url`. It omits GeoJSON geometry. + +`spc_convective_discussion` emits a narrative stanza only when a retained +report-period outlook has severity rank `3` or higher and matching discussion +text is available. Its output includes `included_because` and `discussions`; +each discussion may include `day`, `headline`, `summary`, `discussion`, and +`updated_at`. + ## Boundaries - This package owns module identifiers, config item envelopes, output diff --git a/docs/internal/prompt-input.md b/docs/internal/prompt-input.md index 3c0c77c..2a4989c 100644 --- a/docs/internal/prompt-input.md +++ b/docs/internal/prompt-input.md @@ -68,9 +68,13 @@ Within each category, stanza order follows the module snapshot output order. Current categories are: - `applicable_risk_products`: location-applicable alerts, warnings, outlooks, - discussions, and similar risk products. + and similar risk products. Current stanzas include `alert_digest` and + `spc_convective_outlooks`. - `derived_summaries`: deterministic summaries and calculated report facts. - `narrative_products`: official narrative text products and forecast stories. + Current stanzas include `narrative_forecast`, + `area_forecast_discussion`, `spc_convective_discussion`, and + `weather_story`. - `raw_data`: minimally transformed underlying weather data. ## Boundaries diff --git a/docs/internal/weather-data.md b/docs/internal/weather-data.md index 5857837..55d4817 100644 --- a/docs/internal/weather-data.md +++ b/docs/internal/weather-data.md @@ -60,6 +60,14 @@ non-null `/outlooks/convective` responses with empty outlook and discussion arrays represent checked empty outlook data. `app.FetchAndSaveBundle` can write bundle JSON atomically for inspection. +SPC convective outlook data is stored on +`weatherdata.Bundle.SPCConvectiveOutlooks`. The collected run keeps upstream +run metadata, location identifiers, ordered outlook records, discussion +records, and each outlook's raw GeoJSON geometry. Source provenance for this +payload uses the `spc_convective_outlooks` source name, endpoint +`/outlooks/convective`, the query sent by the adapter, timestamps, and a hash +of the raw `data` object. + ## Skip And Resume Behavior No resume behavior. Optional missing or malformed sources may be omitted,