version: "1.0.0" name: swot-hydro description: "SWOT river and lake products: RiverSP reach vs node scope, LakeSP obs/prior, raster water masks, zipped-shapefile access, discharge products." user-invocable: false

swot-hydro

Background expertise for SWOT inland-water products. This skill carries the method and the one hard refusal, not the dataset facts. The product inventory, granule anatomy, baselines, attribute rules, and uncertainty framing live in the knowledge bundle (knowledge/datasets/swot-river-lake.md and the gotchas that link to it) and are read from there per analysis.

Knowledge first

Before ANY SWOT hydrology analysis, consult installed knowledge concepts first, as the core consult-knowledge skill sets out (the directories to glob, how to voice a concept's status, which concept wins on conflict), by product name, attribute, and topic (RiverSP, LakeSP, reach, node, discharge, wse, quality, simulated). Read every concept that touches the products and quantities in play, restate what each changes about the plan before computing, and cite it by path. A concept added or corrected since you last ran is found this way; that discovery, not this file, is what changes behavior. The concepts this plugin resolves to today:

• the dataset: the product and level inventory with ShortNames,

version families and holdings, granule anatomy, the attributes and their _u fields, the quality gates, the simulated-collection trap: knowledge/datasets/swot-river-lake.md;

• the reach-vs-node scope trap: knowledge/gotchas/swot-reach-node-scope.md;
• the lake products (the Prior Lake Database, LakeSP obs, prior and

unassigned, LakeAvg) as an elevation and area series per prior lake: knowledge/datasets/swot-lakes.md;

• the lake identity trap (the prior file's lake identifier is the key,

the obs file's is a list when lakes merge): knowledge/gotchas/swot-lake-identity-across-passes.md;

• the lake elevation datum (EGM2008, the Version C geoid error, the

prior reference elevation): knowledge/gotchas/swot-lake-elevation-datum.md;

• a lake elevation against a gauge on a national datum:

knowledge/gotchas/swot-gauge-datum-mismatch.md;

• the interactive reach and node series endpoint:

knowledge/connectors/hydrocron-swot.md;

• the lake path for reservoirs without a gauge:

knowledge/recipes/reservoir-storage-change.md.

Everything dataset-specific is read from the bundle, never carried here: version families and current baselines; which _u attributes exist at each aggregation level and what they omit (wse_u total vs wse_r_u random, and the rest); the reach-vs-node scope rule and its volume asymmetry; the discharge algorithm variants and their per-variant _u and _q; the quality attributes that gate features; and which collections are simulated rather than flown.

Method (invariant, not dataset facts)

• Feature product, not a swath. SWOT hydrology spans vector feature

collections and raster water masks; which product is which is in the concept. Handle each in kind: for a vector feature collection you compute statistics over features and QC gates apply to attributes exactly as core QC gates apply them to pixels; do not read a feature product as a gridded swath. The granule mechanics (packaging, per-continent identity, reader) are the concept's to state.

• Aggregation level is part of a result. An aggregated statistic is

meaningless without the level it was computed at; map each question to the level the product answers it at. The specific SWOT levels, their differing attributes, and the volume asymmetry are dataset facts: consult the scope gotcha, do not restate them here.

• Loading is load-swot-hydro's job (volume gate, decode, scope-aware

summary); this skill supplies what it restates.

• A reach elevation against a gauge is scored on changes. The

confrontation recipe (knowledge/recipes/swot-gauge-confrontation.md) runs through uv run ${CLAUDE_PLUGIN_ROOT}/skills/swot-hydro/scripts/load_swot_confrontation.py (the script ships with this plugin beside this file) with --inputs naming the frozen reach and gauge pair, --tolerance-minutes for the pairing window, and --out for the receipt. It reports the level difference as a level difference containing an uncited datum offset, never as a bias, as the gauge datum gotcha sets out.

Must NOT

• **Hard refusal (invariant, universal, fires without consulting

anything):** never present simulated or synthetic collections as observations, and never blend them into an observational series. Passing synthetic data off as flown data is wrong regardless of dataset; WHICH collections are simulated is dataset knowledge, consulted from the concept.

• Never hardcode a baseline, an attribute rule, a discharge variant, or

the reach/node scope rule, and never restate a gotcha here: read them from the dataset and gotcha concepts per the Knowledge-first step, cited. That single-sourcing is what lets a corrected concept change this skill's behavior without editing it.