eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Correct documentation refresh findings

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-31 01:59:13 +00:00
parent 35f4f82e94
commit 5e96790d85
5 changed files with 20 additions and 643 deletions
Download Patch File Download Diff File Expand all files Collapse all files

630
docs/roadmap/implementation.md
View File

@@ -1,630 +0,0 @@
# 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
```sh
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
```sh
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
```sh
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
```sh
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
```sh
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
```sh
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
```sh
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
```sh
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
```sh
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
```sh
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
```sh
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
```sh
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
```sh
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:
```sh
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
```sh
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.