# 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.