weatherreporter/docs/development.md

Development

This is the first-read guide for people and coding agents working on Weatherreporter. It provides a concise repository orientation and routes each kind of change to its canonical documentation.

Weatherreporter is a Go CLI that collects normalized weather data, derives deterministic report facts and module snapshots, executes Promptkit for single-report generated text, renders managed Markdown reports, and can upload completed reports through Distributor. Start with the README for product context and the architecture policy for system boundaries and invariants.

What To Read

When working on	Read	Why
Product behavior or the shortest useful workflow	README, CLI reference, and operations guide	These own product orientation, invocation, and normal operation.
Application shape, package boundaries, dependency direction, safety properties, or architectural invariants	Architecture policy and relevant ADRs under docs/adr/, when present	Architecture defines the intended system; ADRs preserve significant decision rationale.
Any documentation addition, revision, move, or removal	Documentation policy	It defines canonical owners, audience boundaries, current-state rules, and document lifecycle.
Adding, changing, reviewing, or deleting tests	Testing policy and focused package tests	The policy defines risk-based sufficiency, durable test boundaries, doubles, and test-maintenance criteria.
CLI commands, flags, output, quiet mode, or command wiring	CLI reference and CLI internals	The reference owns the user contract; the internal guide owns command composition and output flow.
Configuration fields, defaults, loading, overrides, validation, or secrets	Configuration reference, architecture policy, and tests under internal/config	These separate the user-visible contract, architectural rules, and executable behavior.
Top-level generation, batch, collection, inspection, or notification workflow	App orchestration internals	It owns workflow ordering, persistence points, failure propagation, and orchestration invariants.
Weather API transport, source envelopes, source warnings, or collection	Weather API integration, weather-data internals, and collection internals	These separate the external contract, normalized source facts, and app-facing collection behavior.
Forecast periods, weather derivation, collected facts, or derived facts	Forecast derivation internals and fact contracts	They own deterministic derivation and the fact boundaries used by reports.
Report definitions, valid periods, report IDs, output naming, or batch composition	Report registry internals and app orchestration internals	Report definitions own selection and period rules; orchestration owns execution.
Module IDs, module composition, briefing values, or prompt-facing exports	Module contract internals, module builder internals, and prompt-input internals	These own module contracts, value construction, and the curated prompt-package boundary.
Recent Changes comparison	Changes internals and operations guide	The internal guide owns structured comparison; operations owns user-visible artifact behavior.
Prompt execution, profiles, prompt inputs, or result handling	internal/promptexec, the Promptkit adapter, and prompt-input internals	These separate the executor contract and input construction.
Generated-text schemas, validation, render contexts, templates, or Markdown rendering	Generated-text internals, report-template internals, and report template guide	These own structured text, renderer implementation, and the maintainer-facing template surface.
Workspace paths, metadata, atomic persistence, lookup, inspection, or recovery	State internals, operations guide, and troubleshooting guide	These separate implementation, operator workflows, and symptom-based recovery.
Distributor bundles, uploads, notification artifacts, or failures	Distributor adapter internals, Distributor integration contracts, and operations guide	These separate adapter behavior, external contracts, and operational lifecycle.
Maintained example configuration	Configuration reference and files under examples/	The reference owns field meaning; examples own complete copyable files.
Proposed, deferred, or unimplemented work	Documents under docs/roadmap/	Future behavior and implementation status belong only in roadmaps until implemented.

For an existing subsystem, inspect its focused internal document, package-local types, and tests before changing behavior. Use the package boundaries already present before introducing a new package or abstraction.

Repository Map

Area	Responsibility
cmd/weatherreporter	Binary entry point.
internal/cli	Command parsing, flags, help, output, and command wiring.
internal/app	Generation, batches, collection coordination, notification, and inspection orchestration.
internal/config	Configuration defaults, loading, precedence, secrets, and validation.
internal/adapters	Weather API, Promptkit, Scriptorium batch compatibility, and Distributor boundaries.
internal/weatherdata, internal/forecast, internal/facts	Normalized source facts and deterministic derivation.
internal/report, internal/module, internal/briefing, internal/changes	Report registry, module contracts and values, and structured comparison.
internal/promptinput, internal/generatedtext, internal/reporttemplate	Prompt packages, generated-text validation, render contexts, and Markdown templates.
internal/state, internal/fileutil, internal/timeutil	Durable artifacts, atomic file operations, clocks, dates, timezones, and periods.
docs	User, operator, integration, internal, policy, and roadmap documentation.
examples	Maintained copyable configuration.

The architecture policy is authoritative for normative boundaries. Focused documents under docs/internal/ own detailed implemented subsystem behavior.

Contributor Workflow

1. Read the documents and focused tests identified by the task guide.
2. Use focused package checks while iterating.
3. Run gofmt -w on changed Go files.
4. Update the canonical documentation and maintained examples in the same change when behavior changes.
5. Run repository-wide validation before considering the work complete.

Preserve actionable error context, keep secrets out of logs and fixtures, and avoid validation that requires live Weather API, Scriptorium, or Distributor services. The architecture and testing policies own the detailed rules.

Baseline Validation

Run:

go test ./...
go run ./cmd/weatherreporter --help
git diff --check

Use focused package tests during development and add broader or race-enabled checks when required by the testing policy and the risks of the change.