weatherreporter/docs/internal/reporttemplate.md

Report Template Internals

This document describes embedded Markdown templates and GeneratedText schemas in internal/reporttemplate.

Purpose

internal/reporttemplate owns repository-native report templates and companion GeneratedText JSON schemas. The first implemented template contract is the Hourly Report.

The package embeds assets from:

• internal/reporttemplate/templates/*.md.tmpl
• internal/reporttemplate/schemas/*.schema.json

Inputs And Outputs

Inputs:

• template ID from a report definition
• typed render context built by internal/generatedtext

Outputs:

• template source for inspection and tests
• GeneratedText schema bytes for prompt/schema configuration
• rendered Markdown bytes for app orchestration to persist

The implemented template ID is hourly. The implemented schema ID is also hourly, backed by hourly.generated_text.schema.json.

Boundaries

This package owns embedded asset lookup, Go template parsing, and Markdown template execution. It does not fetch weather data, build module outputs, validate GeneratedText, construct render contexts, choose report definitions, write artifacts, invoke Scriptorium, or notify distributor.

GeneratedText validation is owned by internal/generatedtext. App orchestration decides which template and schema IDs apply to a report through internal/report definitions.

Template Contract

Hourly rendering uses a typed render context with:

• report metadata labels such as title, location, valid period, and generation time
• validated hourly GeneratedText prose slots
• deterministic labels derived from module outputs, including current conditions, hourly forecast rows, precipitation timing, alerts, SPC outlooks, forecast discussion, SPC discussion, and weather story

Templates use text/template with missingkey=error, so missing context fields fail rendering instead of producing incomplete Markdown.

Schema Contract

The hourly GeneratedText schema describes the structured prose Scriptorium is expected to write for the prompt. It requires:

• summary
• forecast_discussion

It allows optional precipitation_timing and confidence, and rejects additional properties. Weather truth remains in module outputs; GeneratedText is limited to prose slots consumed by the template.

Failure Behavior

• Unknown template IDs return actionable lookup errors.
• Unknown schema IDs return actionable lookup errors.
• Template parse errors include the template ID.
• Template execution errors include the template ID and usually identify the missing context field.

Tests

Inspect:

• internal/reporttemplate/reporttemplate_test.go
• internal/generatedtext/render_context_test.go
• internal/app/app_test.go
• internal/cli/root_test.go

Invariants

• Embedded templates and schemas live as separate files, not inline Go strings.
• Report definitions select templates by ID.
• Templates render from curated render contexts, not raw data packages.
• GeneratedText schemas describe LLM prose slots, not deterministic weather facts.