From f23af4301351719ca944253f097da897c2a7ce23 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 29 May 2026 19:49:47 +0000 Subject: [PATCH] Add operational troubleshooting documentation --- docs/operations.md | 141 ++++++++++++------------ docs/troubleshooting.md | 235 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 308 insertions(+), 68 deletions(-) create mode 100644 docs/troubleshooting.md diff --git a/docs/operations.md b/docs/operations.md index 4eb5d88..3271f66 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -1,8 +1,12 @@ # Weatherreporter Operations +This guide covers normal operation, generated artifacts, inspection, recovery, +and current operational caveats. For symptom-specific diagnosis, see +[Troubleshooting](troubleshooting.md). + ## Normal Workflow -The implemented generation workflows are: +Implemented generation commands: ```text weatherreporter generate daily --date 2026-05-29 @@ -10,22 +14,27 @@ weatherreporter generate tomorrow weatherreporter generate three-day weatherreporter generate weekend weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 +``` + +Each command resolves a report period, fetches a Weather API bundle, builds a +briefing, builds a prompt input data package, runs `scriptorium render`, runs +`scriptorium run`, and writes managed artifacts under the configured workspace. +`--out PATH` writes an extra Markdown copy for the current generated report. + +Implemented batch commands: + +```text weatherreporter run morning weatherreporter run evening ``` -These commands fetch weather data, build a briefing for the resolved valid -period, build the prompt input data package, run `scriptorium render`, run -`scriptorium run`, and write inspectable artifacts under the configured -workspace. The evening run resolves only the Tomorrow Planning Brief. The -morning run generates Daily Today and the 3-Day Outlook, plus Weekend Outlook -except on Sunday. Storm Report generation is manual and uses the explicit -`--start` and `--end` bounds as its valid period. - -Scheduled run commands print a JSON aggregate summary to stdout and compact -per-report status lines to stderr. If one report fails, remaining independent -reports are still attempted. The command returns nonzero after the run when any -report failed. +`run morning` generates Daily Today and the 3-Day Outlook, plus Weekend Outlook +except on Sunday. `run evening` generates the Tomorrow Planning Brief. Batch +commands print a JSON summary to stdout, write compact per-report status lines +to stderr, continue independent reports after one report fails, and return +nonzero when any report failed. `--out-dir PATH` writes extra Markdown copies +using report default filenames such as `daily.md`, `three-day.md`, +`weekend.md`, and `tomorrow.md`. ## Filesystem Layout @@ -87,51 +96,37 @@ workspace/ .md ``` -The Markdown report is written to a RunID-managed report path. When `--out` is -provided to `generate daily`, `generate tomorrow`, `generate three-day`, -`generate weekend`, or `generate storm`, the managed report is also copied to -that path. +Managed artifact filenames use the RunID, so repeated runs for the same valid +period do not overwrite each other. -For `run morning` and `run evening`, `--out-dir PATH` writes extra Markdown -copies using each report definition's default filename, such as `daily.md`, -`three-day.md`, `weekend.md`, or `tomorrow.md`. +## RunID And Metadata -## Run Identifiers - -Run IDs are based on generation time plus report ID, such as: +RunIDs are based on generation time plus report ID: ```text 20260529T100000.123456789Z_daily_today ``` -Managed artifact filenames use the RunID so repeated runs for the same valid -date do not overwrite each other. - -## Metadata - Each generated report writes metadata that links: -- RunID -- report ID and prompt ID -- generation time and valid period +- RunID, report ID, variant, and prompt ID +- generation time, timezone, and valid period - source location, source hashes, and source warnings - briefing snapshot path - prompt input data package path - preflight output path -- rendered report path +- managed Markdown report path -Run summaries include each report ID, prompt ID, RunID, status, error text when -applicable, valid period, and artifact paths known to the application. +Batch summaries include report status, error text when applicable, valid +period, and known artifact paths for each attempted report. ## Inspection -Use `weatherreporter inspect reports` to list recent generated runs from the -configured workspace. The output includes RunID, report ID, valid period, -metadata path, briefing path, report path, and source warning count. - -Run-specific inspection commands emit JSON for a single RunID: +Inspection commands read existing workspace artifacts and emit JSON to stdout. +They do not fetch weather data or run `scriptorium`. ```text +weatherreporter inspect reports --limit 10 weatherreporter inspect metadata RUN_ID weatherreporter inspect briefing RUN_ID weatherreporter inspect data-package RUN_ID @@ -139,44 +134,54 @@ weatherreporter inspect prior RUN_ID weatherreporter inspect sources RUN_ID ``` -`inspect prior` shows the prior comparable snapshot selected from stored -metadata, or `null` when none exists. `inspect sources` shows source provenance -and source warnings without dumping full weather payloads. +Use `inspect reports` to find recent RunIDs and artifact paths. Use +`inspect metadata` to see the artifact links recorded for a run. Use +`inspect briefing` and `inspect data-package` to review the exact structured +inputs used for rendering. Use `inspect prior` to see the prior comparable +snapshot selected for Recent Changes, or `null` when none exists. Use +`inspect sources` to review source provenance and warnings without dumping full +weather payloads. ## Recent Changes -When a prior comparable Daily briefing snapshot exists for the same valid local -date, the app compares structured briefing data before writing the prompt input -data package. Daily Today and Daily Tomorrow can compare with each other when -they cover the same valid local date. Meaningful changes are included under -`recentChanges.items`. +Recent Changes are computed from structured briefing snapshots, not rendered +Markdown text. -3-Day Outlook generation compares against a prior compatible 3-Day briefing -snapshot for the same valid local date when one exists. - -Weekend Outlook generation compares against a prior compatible Weekend briefing -snapshot for the same weekend window when one exists. Friday evening and -Saturday runs may narrow the valid start while keeping the same Monday endpoint. - -Storm Report generation currently leaves Recent Changes empty. Its explicit -event window is still recorded in briefing and metadata artifacts. +Daily Today and Daily Tomorrow can compare with each other when they cover the +same valid local date. 3-Day Outlook compares with prior compatible 3-Day +snapshots for the same valid local date. Weekend Outlook compares with prior +compatible Weekend snapshots for the same weekend window. Storm Report currently +leaves Recent Changes empty. When no prior comparable snapshot exists, or no configured threshold is crossed, -the Recent Changes list is empty. +`recentChanges.items` is empty. ## Recovery -If render preflight exits nonzero after producing a result, the captured stdout, -stderr, exit code, and command are still written to the preflight artifact, and -metadata is still written for inspection. +A failed generation run may still leave useful artifacts: -If `scriptorium run` exits nonzero after writing a report, the generated report -and metadata remain available for inspection. Exit code `2` is still returned as -an error because it indicates validation failed, even if report output exists. +- If `scriptorium render` returns a result with a nonzero exit code, the + preflight JSON and metadata are written for inspection. +- If `scriptorium run` exits nonzero after writing a report, the managed report + and metadata remain available. +- For batch commands, inspect the stdout JSON summary first, then inspect the + artifact paths for each failed report. -For scheduled runs, inspect stdout first for the aggregate JSON summary, then -use the per-report artifact paths in that summary to inspect briefing, -data-package, preflight, metadata, and rendered report files. +For a bad report, start with: -The application does not currently implement resume, cleanup, archive, or -remote storage behavior. +```text +weatherreporter inspect metadata RUN_ID +weatherreporter inspect sources RUN_ID +weatherreporter inspect briefing RUN_ID +weatherreporter inspect data-package RUN_ID +weatherreporter inspect prior RUN_ID +``` + +## Operational Caveats + +- The application uses one configured Weather API endpoint. +- The application writes local filesystem state only. +- The application does not implement resume, cleanup, archive, remote storage, + daemon operation, or automatic storm monitoring. +- Generated reports and Scriptorium stderr can contain sensitive operational + context. Store workspace artifacts with appropriate filesystem permissions. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..0c2759e --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,235 @@ +# Weatherreporter Troubleshooting + +This guide lists recurring failures with likely causes, diagnostics, and safe +fixes. See [CLI reference](cli.md), [Configuration reference](config.md), and +[Operations guide](operations.md) for normal usage. + +## `weather_api.base_url is required` + +Symptom: a generation command fails before fetching weather data. + +Likely cause: no Weather API base URL is configured. + +Diagnostic: + +```sh +weatherreporter generate daily --config ./config.yml --date 2026-05-29 +``` + +Safe fix: add `weather_api.base_url` to the config file, or pass the intended +config path with `--config`. + +Relevant docs: [Configuration reference](config.md). + +## `weather_api.base_url must be an absolute URL` + +Symptom: config loading fails with a base URL validation error. + +Likely cause: `weather_api.base_url` is missing a scheme or host. + +Diagnostic: inspect the configured value in the file passed to `--config`. + +Safe fix: use an absolute URL such as `https://weather.api.example.com/`. + +Relevant docs: [Configuration reference](config.md). + +## Invalid Timezone + +Symptom: config loading fails with `weather_api.timezone` context, or a CLI +timezone override fails. + +Likely cause: `weather_api.timezone` or `--tz` is not recognized. + +Diagnostic: + +```sh +weatherreporter generate daily --tz America/Chicago --date 2026-05-29 +``` + +Safe fix: use an accepted timezone value, such as an IANA timezone name, +`Chicago`, `Stl`, a US timezone abbreviation, or a UTC offset. + +Relevant docs: [Configuration reference](config.md). + +## Storm Command Rejects Time Bounds + +Symptom: `generate storm` fails with `requires --start`, `requires --end`, or +`requires --end after --start`. + +Likely cause: the manual event window is missing or invalid. + +Diagnostic: + +```sh +weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 +``` + +Safe fix: provide both bounds. Use `YYYY-MM-DDTHH:MM` in the configured +timezone, or RFC3339 timestamps with explicit offsets. + +Relevant docs: [CLI reference](cli.md). + +## Weather API Fetch Fails + +Symptom: generation fails with `fetch /...`, an HTTP status, or request context. + +Likely cause: the configured Weather API endpoint is unreachable, returned a +non-2xx response, or returned an invalid response envelope. + +Diagnostic: + +```sh +weatherreporter generate daily --config ./config.yml --date 2026-05-29 +``` + +Safe fix: verify `weather_api.base_url`, network access, and the Weather API +service response. The adapter fetches `/observations`, `/conditions/current`, +`/forecast/hourly`, `/forecast/narrative`, `/alerts/active`, and `/discussion`. + +Relevant docs: [Configuration reference](config.md). + +## Hourly Forecast Is Missing + +Symptom: generation fails with hourly forecast context, such as missing hourly +data or an hourly forecast containing no periods. + +Likely cause: hourly forecast data is required for generated reports. + +Diagnostic: check the Weather API response for `/forecast/hourly`. + +Safe fix: restore hourly forecast data at the Weather API. Missing-source +policy cannot make hourly optional. + +Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md). + +## Source Warnings Appear + +Symptom: generation succeeds, but metadata or `inspect sources` shows source +warnings. + +Likely cause: an optional source was missing or malformed under a warning +missing-source policy. + +Diagnostic: + +```sh +weatherreporter inspect sources RUN_ID +weatherreporter inspect metadata RUN_ID +``` + +Safe fix: inspect the warning `source`, `code`, `message`, and `endpoint`. Fix +the upstream optional source, or intentionally change the relevant +`missing_source` policy. + +Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md). + +## `scriptorium` Is Not Found Or Cannot Start + +Symptom: generation fails with `run scriptorium render` or `run scriptorium` +and an executable or OS error. + +Likely cause: the configured Scriptorium binary is unavailable or not +executable. + +Diagnostic: check `scriptorium.binary` in config and run the same binary outside +`weatherreporter`. + +Safe fix: install Scriptorium, update `scriptorium.binary`, or fix executable +permissions. + +Relevant docs: [Configuration reference](config.md), +[Scriptorium integration](integrations/scriptorium.md). + +## Render Preflight Fails + +Symptom: generation fails with `scriptorium render exited with code ...`. + +Likely cause: Scriptorium rejected the prompt, config, profile, or +`data_package` input before report generation. + +Diagnostic: + +```sh +weatherreporter inspect metadata RUN_ID +weatherreporter inspect data-package RUN_ID +``` + +Then read the preflight path from metadata. It contains captured stdout, stderr, +exit code, and command. + +Safe fix: fix the Scriptorium configuration, prompt ID, profile, or data package +input indicated by stderr. + +Relevant docs: [Operations guide](operations.md), +[Scriptorium integration](integrations/scriptorium.md). + +## Scriptorium Run Fails + +Symptom: generation fails with `scriptorium run exited with code ...`. + +Likely cause: Scriptorium failed during report generation or validation. + +Diagnostic: + +```sh +weatherreporter inspect metadata RUN_ID +weatherreporter inspect data-package RUN_ID +``` + +If metadata includes a rendered report path, inspect that report as well. A +nonzero run can still leave a managed report artifact. + +Safe fix: use the captured stderr and data package to fix the Scriptorium +prompt, profile, model configuration, or validation issue. + +Relevant docs: [Operations guide](operations.md), +[Scriptorium integration](integrations/scriptorium.md). + +## Batch Command Returns Nonzero + +Symptom: `run morning` or `run evening` returns nonzero. + +Likely cause: at least one report in the batch failed. + +Diagnostic: inspect stdout for the JSON summary and stderr for compact status +lines. + +Safe fix: use the failed report's artifact paths from the summary, then inspect +metadata, sources, briefing, and data package for that RunID. + +Relevant docs: [CLI reference](cli.md), [Operations guide](operations.md). + +## Unknown RunID + +Symptom: an inspect command fails with `metadata for run id ... was not found`. + +Likely cause: the RunID is mistyped or the command is reading a different +workspace. + +Diagnostic: + +```sh +weatherreporter inspect reports --config ./config.yml --limit 20 +``` + +Safe fix: copy a RunID from `inspect reports`, or use the same `--config` and +workspace that generated the report. + +Relevant docs: [Operations guide](operations.md). + +## Workspace Path Error + +Symptom: startup or inspection fails with workspace path validation or +filesystem read/write context. + +Likely cause: a workspace subdirectory is absolute, escapes `workspace.root`, or +the process cannot read or write the configured path. + +Diagnostic: review `workspace.root`, `workspace.snapshots_dir`, +`workspace.reports_dir`, `workspace.data_packages_dir`, and +`workspace.preflight_dir`. + +Safe fix: keep workspace subdirectories relative to `workspace.root`, and grant +the process appropriate filesystem permissions. + +Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).