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 implemented template contracts are Today Report, Tomorrow Report, and Hourly Report.

The package embeds assets from:

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

Generated-text prompt source files live under internal/reporttemplate/prompts/. They are repository assets for prompt registration, not embedded lookup APIs.

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 IDs are today, tomorrow, and hourly. The implemented schema IDs are also today, tomorrow, and hourly, backed by matching *.generated_text.schema.json files.

The Today generated-text prompt source is internal/reporttemplate/prompts/today.generated_text.md, selected by prompt ID weather.today_generated_text.

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 uses internal/generatedtext catalog lookup to connect internal/report definition schema/template IDs to the matching validator, render-context builder, and embedded assets.

Template Contracts

Today, Tomorrow, and Hourly rendering use typed render contexts with:

• report metadata labels such as title, location, valid period, and generation time
• validated 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

Today and Tomorrow additionally expose forecast-date labels, ordered daypart forecast rows, daily/daypart summaries, planning facts, and a multi-paragraph forecast discussion generated-text slot. The ordered daypart slice is built in Go so templates do not range over maps.

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

Schema Contract

The GeneratedText schemas describe the structured prose Scriptorium is expected to write for each generated-text prompt. Hourly requires:

• summary
• forecast_discussion

Today and Tomorrow require summary and a nonempty forecast_discussion array. All generated-text schemas allow optional precipitation_timing and confidence, and reject 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.