weatherreporter/docs/roadmap/implementation.md

Documentation Refresh Implementation Plan

Status

Accepted for implementation.

This is a temporary, staged coordination plan for refreshing Weatherreporter's current documentation. Implement each stage in order. Do not treat this file as a current-behavior reference.

Objective

Bring every maintained document and example into agreement with:

• the implemented Go application;
• the canonical ownership rules in docs/policy/documentation.md;
• the architectural boundaries in docs/policy/architecture.md;
• the testing rules in docs/policy/testing.md; and
• the contributor routing in docs/development.md.

The completed documentation set must be concise, task-oriented, free of stale or duplicate contracts, and verifiably consistent with the executable sources of truth.

Scope And Constraints

This is a documentation-only refresh.

• Do not add or change product behavior.
• Do not modify Go code, schemas, prompts, or templates to make documentation claims true.
• examples/*.yml may be corrected when they disagree with implemented configuration, because examples are maintained documentation artifacts.
• If code and documentation disagree, document implemented and tested behavior.
• If code appears to violate an architecture or safety policy, do not conceal the conflict with prose and do not fix it during this refresh. Record the conflict in this plan's implementation notes and report it to the maintainer.
• Do not implement any work from docs/roadmap/future.md or docs/roadmap/promptkit.md.
• Preserve the exact contents of AGENTS.md.
• Treat docs/policy/*.md and docs/development.md as the governing baseline. Change them only to repair a link made stale by this refresh; do not reopen their substantive decisions.
• Do not create docs/internal/overview.md; docs/development.md owns the current concise package inventory.
• Do not introduce a release guide, public API guide, consumer guide, or ADR unless a separate maintainer decision expands this plan.
• Preserve unrelated working-tree changes and do not commit unless explicitly instructed.

Executable Authorities

Use codebase-memory graph tools before text search for code discovery. Index the repository first if needed, use search_graph to locate symbols, trace_path for dependencies and impact, and get_code_snippet for exact source. Use graph-augmented search_code or rg for literal flags, paths, errors, schemas, asset names, and configuration values.

The primary authorities for this refresh are:

Contract	Executable authority
CLI commands, flags, help, and dispatch	internal/cli/root.go, internal/report/names.go, and internal/cli/root_test.go
CLI JSON summaries and stdout/stderr behavior	internal/cli/output.go, internal/cli/result.go, and their tests
Configuration fields, defaults, loading, precedence, secrets, templates, and validation	internal/config/*.go and internal/config/config_test.go
Report IDs, modes, periods, modules, output names, comparison, and Distributor paths	internal/report/*.go and internal/report/period_test.go
Application generation, batch, inspection, persistence, and notification order	internal/app/*.go, internal/app/*_test.go, and internal/cli/root_test.go
Weather collection and external Weather API behavior	internal/collect, internal/weatherdata, internal/adapters/weatherapi, fixtures, and focused tests
Facts, forecast derivation, modules, and Recent Changes	internal/facts, internal/forecast, internal/module, internal/briefing, internal/changes, and focused tests
Prompt packages and Scriptorium invocation	internal/promptinput, internal/adapters/scriptorium, and focused tests
Generated text, render contexts, templates, and schemas	internal/generatedtext, internal/reporttemplate, embedded assets, and focused tests
Workspace paths, metadata, atomic writes, prior lookup, and inspection	internal/state, internal/fileutil, and focused tests
Distributor bundle, upload, polling, redaction, and notification behavior	internal/adapters/distributor, internal/app/batch_notification.go, go.mod, and focused tests

Sibling repositories may be used only as secondary integration references. Weatherreporter's pinned dependency, adapter code, and tests determine the subset this repository actually uses. Do not copy broad upstream manuals into this repository.

Rules For Every Stage

For each stage:

1. Read the task-specific entries in docs/development.md.
2. Inspect the listed executable authorities and focused tests.
3. Update only the files assigned to the stage, plus this plan's stage status if progress tracking is requested.
4. Keep exact facts in their canonical owner. Replace duplicate detail with a short stable summary and a relative link.
5. Describe implemented behavior only outside docs/roadmap/.
6. Keep examples synthetic, valid, and secret-free.
7. Use language tags on every fenced block.
8. Run the stage validation before proceeding.
9. Do not reinterpret surprising behavior as intent; tests and executable contracts take precedence over old prose.

Stage 1: Inventory And Mechanical Hygiene

Files

• README.md
• all Markdown files under docs/
• examples/*.yml

Work

1. Classify every document under the ownership table in docs/policy/documentation.md. Do not create a separate permanent inventory document.
2. Identify duplicated exact contracts, stale paths, broken links, untagged code fences, and current-state claims in the wrong document.
3. Repair mechanical link and path defects that do not require content redesign.
4. In docs/integrations/distributor/pkg-bundle.md, remove the broken local link to ../integrations/source-bundle.md. Identify the upstream canonical file as docs/integrations/source-bundle.md in the Distributor repository using prose or code formatting, not a nonexistent repository-relative link.
5. In docs/integrations/distributor/pkg-upload.md, do the same for the broken ../integrations/http-upload.md link.
6. Confirm that no document references the retired development-policy path.
7. Defer substantive rewrites to the assigned later stage; this stage should establish a clean mechanical baseline.

Acceptance

• Every repository-relative link target exists.
• All fenced blocks have language tags.
• No stale development-policy reference remains.
• No future feature is presented as current behavior outside docs/roadmap/.
• git diff --check passes.

Stage 2: CLI, Configuration, And Examples

Files

• docs/cli.md
• docs/config.md
• examples/minimal-config.yml
• examples/config.yml

CLI Work

1. Regenerate the command inventory from go run ./cmd/weatherreporter --help and verify it against internal/cli/root.go and report command-name tests.
2. Keep this document's order:
   • shortest useful command;
   • command overview and complete usage;
   • stdout, stderr, JSON summary, quiet-mode, and exit behavior;
   • complete flag reference;
   • concise invocation examples; and
   • inspection commands.
3. Keep exact command syntax and output semantics here. Move or replace operational workflow explanations with links to operations.md.
4. Verify all seven generate commands, both batch commands, and every inspect command.
5. Verify command-specific restrictions: required Daily date, optional Today date, Storm bounds, Hourly restrictions, generate output copies, batch output directories, and inspection quiet-mode rejection.

Configuration Work

1. Compare every documented field and default with Config, Defaults, loading, secret loading, report overrides, notification templates, and validation code.
2. Keep discovery, precedence, fields, defaults, accepted values, validation rules, secret-supply behavior, and links to examples here.
3. Keep operational notification sequencing, filesystem lifecycle, and recovery in operations.md; summarize and link rather than duplicate them.
4. Verify report-module override keys against the report registry and module registry.
5. Verify every template placeholder accepted by Distributor notification configuration.

Example Work

1. Ensure both examples contain only implemented fields and synthetic endpoints.
2. Keep minimal-config.yml genuinely minimal.
3. Keep config.yml production-oriented and representative without becoming a second field reference.
4. Do not add credentials, private endpoints, or generated reports.

Validation

go run ./cmd/weatherreporter --help
go test ./internal/cli ./internal/config ./internal/report ./internal/module
git diff --check

The config tests must load the maintained examples successfully.

Stage 3: README And Operations

Files

• README.md
• docs/operations.md

README Work

Keep the README short and in this order:

1. concise product description;
2. one-sentence value proposition;
3. the shortest successful generation command; and
4. links to CLI, configuration, operations, troubleshooting, development, and architecture documentation.

Do not add a complete command list, configuration fields, workspace layout, or future Promptkit behavior.

Operations Work

1. Verify generation and batch workflow order against internal/app.
2. Verify the physical workspace tree, artifact names, RunID placement, metadata links, notification artifact placement, and prior lookup against internal/state.
3. Verify output-copy behavior and the rule that managed reports are the only upload sources.
4. Verify single-report and batch notification sequencing, skip conditions, failure accounting, and inspectable artifacts.
5. Verify inspection is read-only and identify exactly which artifacts each command reads.
6. Keep normal operation, state lifecycle, inspection, recovery, and operational caveats here.
7. Replace complete flag or config-field definitions with links to their canonical references.
8. Keep only the minimal commands needed to illustrate an operational procedure.

Validation

go test ./internal/app ./internal/state ./internal/cli
go run ./cmd/weatherreporter --help
git diff --check

Stage 4: Troubleshooting

File

• docs/troubleshooting.md

Work

1. Verify every documented symptom and diagnostic fragment against current errors and failure tests.
2. Use one consistent entry shape:
   • symptom;
   • likely cause;
   • diagnostic step or command;
   • safe fix; and
   • links to canonical references.
3. Keep symptom-oriented diagnosis here. Remove repeated normal workflows, full endpoint inventories, config-field definitions, and artifact schemas.
4. Preserve the distinction between pre-run failures, collection failures, Scriptorium preparation/run failures, generated-text validation failures, template failures, report failures, batch partial failures, skipped batch uploads, Distributor failures, secret loading, and state lookup failures.
5. Use exact error text only when it is a stable operator-facing contract; otherwise use the smallest stable identifying fragment.
6. Ensure fixes are safe, narrow, and do not recommend broad workspace deletion or expose secret values.

Validation

go test ./internal/cli ./internal/config ./internal/app ./internal/state
go test ./internal/adapters/weatherapi ./internal/adapters/scriptorium ./internal/adapters/distributor
git diff --check

Stage 5: Report Template Guide

File

• docs/templates.md

Work

1. Verify top-level templates, shared partials, schema IDs, prompt sources, and registered template functions against internal/reporttemplate.
2. Verify every documented render-context field against internal/generatedtext; remove fields that are absent and add implemented fields needed by maintainers.
3. Keep the maintainer-facing editing rules, context contracts, and minimal template examples here.
4. Clearly distinguish deterministic module values, collected/derived facts, and validated GeneratedText prose.
5. Keep weather derivation and generated-text validation mechanics in their internal owners; summarize and link from this guide.
6. Avoid duplicating the full JSON schema bodies or package implementation flow.

Validation

go test ./internal/reporttemplate ./internal/generatedtext ./internal/app
git diff --check

Stage 6: Weather API Integration

File

• docs/integrations/weatherapi.md

Work

1. Verify URL joining, query parameters, timeout and retry behavior, response envelope, endpoint set, decoding, source identity, warnings, and required/optional source behavior against the adapter, collection layer, fixtures, and tests.
2. Keep the external Weather API contract and compatibility assumptions here.
3. Move internal normalization and orchestration mechanics to links pointing at the relevant internal documents.
4. Document only endpoints and fields Weatherreporter currently consumes.

Validation

go test ./internal/adapters/weatherapi ./internal/collect ./internal/weatherdata
git diff --check

Stage 7: Scriptorium Integration

File

• docs/integrations/scriptorium.md

Work

1. Verify the exact render and run invocations, argument ordering, timeouts, output paths, result decoding, stderr handling, cancellation, and failure behavior against the adapter and tests.
2. Keep the external CLI contract here and link to internal prompt-input, adapter, generated-text, and orchestration mechanics.
3. Describe Scriptorium as the implemented runtime. Do not mention the proposed Promptkit replacement outside docs/roadmap/promptkit.md.
4. Do not copy Scriptorium's general manual; document only the commands and result fields Weatherreporter uses.

Validation

go test ./internal/adapters/scriptorium ./internal/promptinput ./internal/app
git diff --check

Stage 8: Distributor Integration

Files

• docs/integrations/distributor/api.md
• docs/integrations/distributor/pkg-bundle.md
• docs/integrations/distributor/pkg-upload.md

Work

1. Rewrite these as concise references to the exact Distributor surface used by Weatherreporter:
   • api.md owns accepted upload, authentication, idempotency, run status, terminal failure, and retention assumptions used by the adapter;
   • pkg-bundle.md owns the bundle file mapping and path constraints used by Weatherreporter;
   • pkg-upload.md owns the client construction, upload, retry, conflict, and status operations used by the adapter.
2. Remove generic producer tutorials, broad upstream feature descriptions, unrelated examples, and claims Weatherreporter does not rely on.
3. Verify the pinned module version in go.mod and the adapter's actual calls.
4. Use the sibling Distributor repository only to confirm the pinned API. Do not make Weatherreporter documentation depend on sibling-relative links.
5. Keep internal request construction, redaction, polling decisions, and app notification order in internal documents.
6. Ensure all local links resolve and upstream canonical paths are identified without pretending those files exist in this repository.

Validation

go test ./internal/adapters/distributor ./internal/app ./internal/config
git diff --check

Stage 9: CLI, Collection, And App Internals

Files

• docs/internal/cli.md
• docs/internal/collect.md
• docs/internal/app-orchestration.md

Work

Verify purpose, inputs and outputs, ownership boundaries, workflow composition, failure propagation, focused tests, and invariants. Keep public CLI syntax in docs/cli.md, Weather API wire behavior in its integration document, and physical state layout in docs/operations.md or docs/internal/state.md.

The app document may retain explicit workflow ordering because orchestration is its owned internal contract. It must not duplicate complete config, CLI, or external protocol references.

Validation

go test ./internal/cli ./internal/collect ./internal/app
git diff --check

Stage 10: State, Source, And Adapter Internals

Files

• docs/internal/state.md
• docs/internal/weather-data.md
• docs/internal/scriptorium-adapter.md
• docs/internal/distributor-adapter.md

Work

1. Verify each document against its package and focused tests.
2. Keep state path derivation, metadata ownership, prior lookup, atomic writes, and inspection mechanics in the state document.
3. Keep normalized bundle, source metadata, and warning semantics in the weather-data document.
4. Keep argv/result translation in the Scriptorium adapter document and dependency/client translation in the Distributor adapter document.
5. Link external contracts and user-facing references rather than repeating them.

Validation

go test ./internal/state ./internal/weatherdata
go test ./internal/adapters/scriptorium ./internal/adapters/distributor
git diff --check

Stage 11: Deterministic Domain Internals

Files

• docs/internal/facts.md
• docs/internal/forecast-derivation.md
• docs/internal/changes.md

Work

Verify fact ownership, derivation inputs, period and daypart behavior, thresholds, comparison strategies, missing-data behavior, failures, tests, and invariants. Keep these documents deterministic and independent of CLI, filesystem, subprocess, and transport mechanics. Link configuration defaults instead of restating them.

Validation

go test ./internal/facts ./internal/forecast ./internal/changes ./internal/timeutil
git diff --check

Stage 12: Reports, Modules, Briefing, And Prompt Input

Files

• docs/internal/report-registry.md
• docs/internal/module.md
• docs/internal/briefing.md
• docs/internal/prompt-input.md

Work

1. Verify all report definitions, registry fields, valid periods, batch membership, comparison policy, output naming, module defaults, and Distributor path declarations.
2. Verify registered module IDs, options, rich values, prompt exports, composition by report, and missing-source behavior.
3. Verify prompt package schema, ordering, metadata, serialization, validation, and the boundary between rich module values and prompt-facing exports.
4. Keep exact CLI command syntax, config defaults, integration protocol, and rendered template contracts in their canonical owners.
5. Prefer tables for report-to-module or report-to-mode mappings where they materially reduce repeated prose.

Validation

go test ./internal/report ./internal/module ./internal/briefing ./internal/promptinput
git diff --check

Stage 13: Generated Text And Template Internals

Files

• docs/internal/generatedtext.md
• docs/internal/reporttemplate.md

Work

Verify catalog registration, schema selection, decoding and validation, generated-text types, render-context construction, embedded asset lookup, template parsing, partials, failure behavior, and invariants. Keep the complete maintainer-facing context-field reference in docs/templates.md; internal documents should explain implementation and link to that contract.

Validation

go test ./internal/generatedtext ./internal/reporttemplate ./internal/app
git diff --check

Stage 14: Roadmap Review

Files

• docs/roadmap/future.md
• docs/roadmap/promptkit.md

Work

1. Ensure every roadmap item is explicitly unimplemented, proposed, accepted, deferred, or rejected.
2. Remove or rewrite work that has already been implemented.
3. Keep current-state summaries minimal and link to canonical current documentation instead of reproducing it.
4. In future.md, correct the Distributor enhancement introduction so it acknowledges implemented single-report and batch notification without maintaining their detailed current contract.
5. Preserve the Promptkit roadmap as future migration policy. Do not implement it, resolve its product-design open questions, or describe it as current.
6. Ensure future architecture does not leak into README, user/operator docs, integrations, or current internal docs.

Validation

rg -n "Promptkit|promptkit" README.md docs \
  --glob "*.md" --glob "!docs/roadmap/**"
git diff --check

The Promptkit search must return no current-state documentation matches.

Stage 15: Cross-Document Consistency And Final Validation

Semantic Review

Verify these cross-document facts have one exact owner and consistent summaries elsewhere:

• seven generate report commands;
• four generated-text-template reports and three direct-Markdown reports;
• morning and evening batch membership and future Daily eligibility;
• configuration precedence and defaults;
• module and report IDs;
• managed workspace and notification paths;
• Recent Changes structured comparison;
• Scriptorium preflight and run behavior;
• single-report and batch Distributor behavior;
• output copies versus managed upload sources; and
• inspection's read-only behavior.

Remove duplicate exact tables or narratives from non-owning documents. Preserve short task-relevant summaries and relative links.

Link Validation

Check every Markdown link in README.md and docs/. Repository-relative targets and changed heading anchors must resolve. No maintained document may depend on sibling checkout paths.

At minimum, run a repository-relative target check equivalent to:

find README.md docs -type f -name "*.md" -print0 |
  while IFS= read -r -d "" file; do
    dir=$(dirname "$file")
    rg -o '\]\([^)]+\)' "$file" |
      sed -E 's/^\]\(([^)#]+)(#[^)]+)?\)$/\1/' |
      while IFS= read -r target; do
        case "$target" in
          http:*|https:*|mailto:*) continue
        esac
        test -z "$target" || test -e "$dir/$target" ||
          printf '%s -> %s\n' "$file" "$target"
      done
  done

Manually verify anchors on every changed link because the target check does not validate fragments.

Final Commands

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

Review git diff --name-only and confirm the refresh changed only Markdown and maintained YAML examples. Confirm no secrets, private endpoints, generated artifacts, code changes, go.work, or local module replacements were added.

Completion Criteria

The refresh is complete when:

• every document has one clear canonical owner;
• current user and operator documentation matches implemented behavior;
• CLI and configuration references are complete and verified;
• examples load and contain no secrets;
• operation, recovery, template, and integration contracts are accurate;
• internal documents preserve package boundaries without duplicating public references;
• roadmaps contain only future or coordination material;
• all repository-relative links and changed anchors resolve;
• all validation commands pass; and
• no unresolved architecture-policy conflict was hidden or implemented as part of the documentation work.

After all stages are accepted, remove this temporary implementation plan in a final documentation-only change. Do not move its task sequencing or completion history into current-state documentation.