79afe11da8
Some checks failed
CI / lint-and-test (push) Has been cancelled
Four decisions recorded under .agents/decisions/ per project convention (DECISION-YYYYMMDD-slug.md) to close the loop on today's pumpingStation refactor + eval + docs work: - wiki-in-code-repo — why docs+diagrams+code now live in one package - 5-threshold-naming — old/new field mapping + breaking-change rationale - mode-tier-template — Tier 1/2/3 classification for mode pages - eval-harness — why eval/ exists alongside test/ Also bumps nodes/pumpingStation to 66fd3fe (eval harness + Tier 2/3 template pages). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
47 lines
2.8 KiB
Markdown
47 lines
2.8 KiB
Markdown
# DECISION-20260422-pumpingstation-mode-tier-template
|
||
|
||
## Context
|
||
- Task/request: Document each pumpingStation control mode uniformly so operators can compare them and contributors can add new ones from a template.
|
||
- Impacted files/contracts: `wiki/modes/*.md`, `wiki/diagrams/modes/*.drawio.svg`.
|
||
- Why a decision is required now: The initial `levelbased.md` used a 2D `demand-vs-level` transfer-function plot. That plot form works for static memoryless control but misleads for modes whose curve shape changes at runtime (e.g. `powerBased`) or where there is no curve at all (`mpc`). We need one template that stretches to cover all cases.
|
||
|
||
## Options
|
||
1. One template, transfer-function only
|
||
- Benefits: Uniformity.
|
||
- Risks: Silently misleading for Tier-2/Tier-3 modes where the "curve" is not well-defined.
|
||
|
||
2. Per-mode ad-hoc diagrams
|
||
- Benefits: Each mode gets the best visual for itself.
|
||
- Risks: No common vocabulary — comparing modes becomes harder.
|
||
|
||
3. Three-tier template (selected)
|
||
- Benefits: Classifies every mode into one of three buckets, each with a dedicated diagram type. Still one template — only the diagram section branches.
|
||
- Risks: Some modes don't fit cleanly; will need judgement.
|
||
|
||
## Tier definitions
|
||
|
||
| Tier | Control surface | Example modes | Diagrams |
|
||
|---|---|---|---|
|
||
| 1 | Static: `demand = f(x)` memoryless | `levelbased`, `manual` | Single-curve transfer function |
|
||
| 2 | Parameterised: shape fixed, curve moves with `θ(t)` | `flowbased` (PID), `pressureBased`, `percentageBased`, `powerBased` | Transfer function + parameter-overlay / family-of-curves |
|
||
| 3 | Optimisation / horizon: no fixed curve | `hybrid-optimal`, `mpc`, weather-aware | Block diagram of signal flow + scenario time-series |
|
||
|
||
## Decision
|
||
- Selected option: Option 3 — three-tier classification with diagram type per tier.
|
||
- Decision owner: User
|
||
- Date: 2026-04-22
|
||
- Rationale: Keeps the mode pages comparable (same six sections) while being honest about what's actually drawable. Tier-3 modes get scenario-based analysis (via the `eval/` harness) instead of a fictitious static curve.
|
||
|
||
## Consequences
|
||
- Compatibility impact: None — this is doc-level.
|
||
- Safety/security impact: None.
|
||
- Data/operations impact: New modes get a template to follow; reviews have a shared vocabulary.
|
||
|
||
## Implementation Notes
|
||
- Required code/doc updates: `wiki/modes/README.md` lists the tiers and template; `wiki/modes/{flowbased, powerbased, mpc}.md` are worked templates covering Tier 2 (×2) and Tier 3 (×1) respectively.
|
||
- Validation evidence required: A reviewer reading a mode page can identify which tier it is within 10 seconds without scrolling.
|
||
|
||
## Rollback / Migration
|
||
- Rollback strategy: Delete `wiki/modes/`; revert the table in `wiki/README.md`.
|
||
- Migration/deprecation plan: N/A — adding a tier later (e.g. Tier 4 — RL-based) is trivially additive.
|