weatherreporter/docs/roadmap/implementation.md

# Domain-Specific Prompt Profiles Implementation Plan

Status: Completed.

## Purpose And Authority

This document records the completed implementation of the
[domain-specific prompt profiles roadmap](domain-profiles.md). The roadmap is
authoritative for scope, user intent, policy choices, and the implemented end
state. This plan records the implementation sequence, verification, and exit
gates used to reach it.

This plan follows the repository's
[architecture](../policy/architecture.md),
[documentation](../policy/documentation.md), and
[testing](../policy/testing.md) policies.

## Completed Prerequisite

Weatherreporter is already pinned to Promptkit v0.5.0. That release provides
the public `WithFallbackProfileFS` option and the required precedence across
inspection, preparation, and execution. The dependency upgrade passed
Weatherreporter's full offline test suite, race-enabled suite, CLI help check,
and an operator `generate hourly` smoke test. Do not repeat or replace the
dependency upgrade as part of these stages.

## Locked Product Decisions

Implement these exact Weatherreporter-owned profiles:

| Profile ID | Backend | Model | Reasoning effort | Timeout | Service tier |
| --- | --- | --- | --- | --- | --- |
| `weather-light` | `openrouter` | `deepseek/deepseek-v4-flash` | Omitted | 180 seconds | `flex` |
| `weather-balanced` | `openrouter` | `~google/gemini-flash-latest` | `high` | 240 seconds | `flex` |
| `weather-deep` | `openrouter` | `~anthropic/claude-sonnet-latest` | `high` | 240 seconds | `flex` |

Assign Hourly to `weather-light`; assign Daily, Today, and Tomorrow to
`weather-balanced`; assign no report to `weather-deep` initially. Advance all
four prompt definitions and matching report-registry entries from `1.0.1` to
`1.1.0` when their defaults change.

The leading `~` in the Gemini and Claude model IDs is required and denotes an
OpenRouter rolling alias. Do not substitute the unavailable non-tilde IDs or a
dated model version. Do not add temperature, `top_p`, maximum-token, endpoint,
or credential fields to the embedded definitions.

Prompt preparation and execution artifacts written at `1.0.1` are not required
to remain readable after the transition to `1.1.0`. Do not add a migration,
compatibility shim, or weaker historical-artifact validation for this feature.

Definition lookup must remain:

1. explicit Promptkit in-memory profiles used by tests or an embedding
   consumer;
2. Weatherreporter's configured `profile_file` or `profile_dir` source;
3. Weatherreporter's embedded fallback profiles; and
4. Promptkit's built-in catalog.

Selection remains a separate concern: a nonblank global `promptkit.profile`
selects the profile for every report in the invocation; otherwise the exact
prompt definition's `default_profile` selects it. A malformed matching
higher-precedence profile is an error and never falls through.

## Continuing Invariants

- Keep all Promptkit types and mechanics inside
  `internal/adapters/promptkit`, its focused tests, and asset contract tests.
- Keep prompt inspection before weather collection and provider work.
- Keep one Promptkit engine per command action and one shared engine across a
  sequential batch.
- Preserve logical profile ID and effective backend/model information through
  active inspection and execution where the project-owned contract already
  exposes it. Do not add new durable-provenance fields or compatibility
  guarantees.
- Leave existing workspace persistence behavior otherwise unchanged. The
  accepted [ephemeral-state roadmap](ephemeral-state.md) owns its future
  removal and must not be partially implemented here.
- Do not expose endpoints, credentials, rendered messages, schemas, request
  bodies, response bodies, or complete parameter maps through ordinary errors,
  logs, summaries, or state.
- Keep the default suite deterministic, offline, and credential-free.
- Do not add endpoint discovery, health probing, provider failover, retries at
  a more expensive tier, profile merging, per-report configuration fields, or
  severity-driven model selection.
- Update canonical current-state documentation only in the stage where the
  corresponding behavior becomes implemented.
- Run `git diff --check` before completing every stage.

## Stage 1: Add The Embedded Weather Profile Catalog

### Goal

Create one repository-owned, embedded profile source containing exactly the
three locked logical profiles.

### Work

1. Add strict YAML profile assets beneath `internal/promptassets` using the
   exact IDs and definitions in this plan.
2. Extend `internal/promptassets` with a narrowly named accessor that returns
   the embedded profile `fs.FS`. Follow the existing prompt and schema asset
   pattern without exposing Promptkit types from the package.
3. Keep profile filenames and embed layout simple and deterministic. Do not
   duplicate Promptkit's built-in directory taxonomy unless the application
   assets require it.
4. Validate the assets through Promptkit's public engine/profile inspection
   surface rather than adding a second YAML parser or a Weatherreporter-owned
   profile representation.

### Tests

- Extend the asset contract tests to assert exactly the three logical IDs,
  their exact effective model IDs, and the intentional parameters.
- Prove all three profiles inspect successfully offline when supplied as a
  fallback source and no operator source is present.
- Assert that the catalog contains no endpoints, credentials, temperature,
  `top_p`, or maximum-token settings.
- Run:

  ```sh
  go test ./internal/promptassets
  git diff --check
  ```

### Exit Gate

The embedded catalog is complete, strictly valid, safe, and independently
inspectable through Promptkit v0.5.0's public API.

## Stage 2: Wire Fallback Resolution And Protect Precedence

### Goal

Supply the embedded catalog through Promptkit's application fallback layer
without changing existing operator configuration or application boundaries.

### Work

1. Add `promptkit.WithFallbackProfileFS(promptassets.ProfileFS(), ".")` to
   normal adapter engine construction.
2. Preserve existing `profile_file`, `profile_dir`, configured local backend,
   timeout, prompt filesystem, schema filesystem, and test-option behavior.
3. Ensure ordinary production construction and the adapter's test
   construction path exercise the same fallback wiring. Test-only explicit
   profiles may retain Promptkit's documented highest precedence.
4. Keep all fallback resolution in Promptkit. Do not add filesystem overlays,
   existence checks, YAML parsing, or merge behavior to Weatherreporter.

### Tests

- At the adapter boundary, prove fallback-only inspection of all three
  Weatherreporter profiles.
- Prove same-ID overrides through both configured `profile_file` and
  `profile_dir`, including resolution of the override's effective backend and
  model.
- Prove an absent operator match falls through, while a malformed matching
  operator definition fails without using the embedded profile.
- Prove a selected Promptkit built-in that is absent from both higher layers
  still resolves.
- Prove an explicit in-memory test profile retains highest precedence.
- Cover both local override forms required by the roadmap: an endpoint-only
  OpenAI-compatible `weather-light` profile and a `backend: local` profile
  using the configured local endpoint. No test may contact either endpoint.
- Run:

  ```sh
  go test ./internal/adapters/promptkit
  git diff --check
  ```

### Exit Gate

Inspection and prepared execution use Promptkit's exact four-layer precedence,
operator errors remain visible, and local overrides require no prompt or code
changes.

## Stage 3: Adopt Logical Defaults And Prompt Version 1.1.0

### Goal

Move operational prompts from provider-oriented defaults to the three-tier
Weatherreporter policy with an exact, synchronized version transition.

### Work

1. Change Hourly's `default_profile` to `weather-light`.
2. Change Daily, Today, and Tomorrow to `weather-balanced`.
3. Advance the exact version in all four prompt YAML assets from `1.0.1` to
   `1.1.0` without changing prompt text or generated-text schemas solely for
   this feature.
4. Advance the four matching report-registry prompt versions to `1.1.0` in the
   same change. Keep prompt IDs, report IDs, modules, periods, templates, and
   output contracts unchanged.
5. Update fixtures and expectations that intentionally assert the current
   prompt contract. Do not rewrite historical fixture versions or weaken tests
   that protect actual compatibility.

### Tests

- Update asset and report-registry contract tests to require exact version
  `1.1.0` and the report-to-profile assignments locked in this plan.
- Inspect every exact prompt version through the real embedded prompt, schema,
  and fallback-profile filesystems.
- Prove Hourly resolves DeepSeek V4 Flash, the three day-scale reports resolve
  Gemini Flash Latest, and `weather-deep` remains inspectable but unassigned.
- Run:

  ```sh
  go test ./internal/promptassets ./internal/report ./internal/adapters/promptkit
  git diff --check
  ```

### Exit Gate

Every operational prompt and registry definition agrees on exact version
`1.1.0`, selects its intended logical tier, and resolves its expected effective
model offline.

## Stage 4: Verify Application Selection And Batch Reuse

### Goal

Protect the assembled application behavior created by the new defaults and
confirm that logical identity is not lost during active effective-model
resolution.

### Work

1. Preserve the current pre-collection inspection order and fail-fast behavior
   for missing credentials, unknown profiles, malformed profiles, and unusable
   backends.
2. Preserve the global `promptkit.profile` all-report override. Do not add a
   second override mechanism or report-specific configuration fields.
3. Preserve batch preflight deduplication by selected effective profile ID:
   Today and Tomorrow in the same batch should inspect their shared
   `weather-balanced` selection once.
4. Preserve the selected logical profile ID and resolved backend/model through
   active inspection, preparation, and execution using the existing
   project-owned contract. Do not add state fields, expand persisted parameter
   detail, or create a new historical compatibility guarantee.

### Tests

- Add or update representative app tests for default Hourly and day-scale
  selection, a global-profile override, and a morning/evening batch sharing
  `weather-balanced`.
- Assert inspection completes before weather collection and provider
  generation, including malformed same-ID operator overrides.
- Assert active inspection and execution expose the logical profile ID and
  effective model for both embedded and overridden profiles.
- Assert endpoints and credentials remain absent from errors, summaries,
  normal logs, and ordinary state.
- Use project-owned executor fakes or Promptkit provider fakes; do not make live
  provider calls.
- Run:

  ```sh
  go test ./internal/app ./internal/cli
  git diff --check
  ```

### Exit Gate

Single-report and batch workflows select the intended tier, retain existing
override and preflight behavior, deduplicate shared batch inspection, and
preserve safe logical and effective model information during active execution
without adding a durable-provenance contract.

## Stage 5: Publish Canonical Operator And Maintainer Documentation

### Goal

Document the implemented feature once in each canonical owner and provide one
maintained, copyable local override example.

### Work

1. Update `docs/config.md` to explain global profile selection versus
   `profile_file`/`profile_dir` definition lookup and link to the maintained
   example. Keep the field reference in this canonical document.
2. Update the Promptkit integration document with the logical profile catalog,
   source precedence, exact prompt-version relationship, and safe active
   inspection and execution contract. Avoid restating complete configuration
   syntax or presenting transitional persistence as the target architecture.
3. Update the report-registry, Promptkit adapter, app-orchestration, and state
   internal documents only where their implemented contracts changed.
4. Update `docs/operations.md` with the normal local-override workflow and
   `docs/troubleshooting.md` with malformed override, unavailable local
   endpoint, missing credential, and unexpected effective-model diagnostics.
5. Add or update one secret-free file under `examples/` showing a
   `weather-light` override for a local OpenAI-compatible endpoint. Choose one
   supported form as the complete example and mention the other form only in
   its canonical reference.
6. Update the architecture policy only if implementation changed a normative
   boundary or invariant. Do not add future behavior to current-state docs.
7. Keep the feature roadmap and this plan in their pre-implementation statuses
   until the final repository gate passes. Do not create release notes before
   a release version is chosen.

### Tests

- Verify every changed repository-relative link and every profile/model ID.
- Validate maintained YAML examples through the same strict configuration or
  Promptkit profile path used by production where practical.
- Run the focused tests that own any executable examples, followed by:

  ```sh
  git diff --check
  ```

### Exit Gate

Users, operators, and maintainers can discover the tier defaults, precedence,
global override, local override, and failure behavior without duplicated or
future-state documentation.

## Stage 6: Complete Repository Verification And Roadmap Handoff

### Goal

Demonstrate that the complete feature is coherent, offline-testable, and ready
for review and a later release decision.

### Work

1. Review the complete diff against the roadmap, this plan, and all three
   policy documents. Remove stale identifiers, temporary helpers, redundant
   tests, and documentation duplication.
2. Confirm `go.mod` and `go.sum` retain tagged Promptkit v0.5.0 without a local
   replacement or dependency drift.
3. Confirm only the four supported report products exist and no retired report
   surfaces were reintroduced.
4. Confirm the roadmap's completion criteria one by one. Change its status to
   implemented and this plan's status to completed only after every criterion
   and command below passes.
5. Do not require a live provider for completion. If credentials and network
   access are deliberately supplied by an operator, record live smoke results
   separately as release-candidate evidence rather than adding them to the
   default suite.

### Verification

Run `gofmt -w` on every changed Go file, then run:

```sh
go test ./...
go test -race ./...
go run ./cmd/weatherreporter --help
git diff --check
git status --short
```

Also inspect all three logical profiles through the application's normal
preflight path using offline provider doubles, including one same-ID local
override and one explicit global override.

### Exit Gate

All roadmap completion criteria are satisfied, all verification commands pass,
the working tree contains only intentional changes, and the canonical
documentation describes the implemented state. The feature is ready for code
review and release preparation.

## Open Questions

None. The model identifiers, profile settings, report assignments, version
transition, precedence, compatibility behavior, test boundaries, and
documentation ownership are decision-complete.