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>
2.8 KiB
2.8 KiB
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.mdused a 2Ddemand-vs-leveltransfer-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
- One template, transfer-function only
- Benefits: Uniformity.
- Risks: Silently misleading for Tier-2/Tier-3 modes where the "curve" is not well-defined.
- Per-mode ad-hoc diagrams
- Benefits: Each mode gets the best visual for itself.
- Risks: No common vocabulary — comparing modes becomes harder.
- 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.mdlists the tiers and template;wiki/modes/{flowbased, powerbased, mpc}.mdare 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 inwiki/README.md. - Migration/deprecation plan: N/A — adding a tier later (e.g. Tier 4 — RL-based) is trivially additive.