opencode-skills-collection 4.0.74 → 4.0.76

package/bundled-skills/nexrad-mosaic-construction/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: nexrad-mosaic-construction
+description: "Construct a quality-aware NEXRAD multi-radar mosaic from aligned single-site products with explicit coverage, beam geometry, quality weighting, overlap resolution, and provenance."
+category: analysis
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-25"
+author: ShianMike
+tags: [weather, nexrad, mosaic, multi-radar, quality-weighting, coverage, overlap-resolution]
+tools: [claude, cursor, gemini, codex]
+---
+
+# NEXRAD Mosaic Construction
+
+## Overview
+
+Build a custom multi-radar composite from aligned, validated single-site data.
+Every output pixel must have a traceable source, coverage state, and quality
+decision. Preserve the distinction between a local analysis product and an
+official provider mosaic.
+
+Use this skill after products from multiple radars have been resolved. It does
+not discover, download, or decode source files. Use `nexrad-product-access` for
+single-site access and `nexrad-mosaic-access` when the required result is an
+existing NOAA MRMS composite rather than a newly constructed analysis.
+
+## When to Use This Skill
+
+- Combine two or more radars to cover a region with overlapping or adjacent
+  fields.
+- Construct a consistent base-reflectivity, velocity, spectrum-width, or
+  dual-polarization composite.
+- Build a research mosaic on a common grid or for a cross-radar comparison.
+- Compare a custom mosaic with an official MRMS product.
+- Visualize source contributions and coverage gaps in a composite.
+
+Do not use this skill to fetch an official MRMS product, select a single radar,
+or claim that a simple pixel average is a physically resolved regional field.
+
+## Define the Mosaic Contract
+
+Record:
+
+- product and exact units from each source;
+- source sites, coordinates, volume start/end times, and sweeps;
+- target region, output grid, projection, and cell size;
+- time-matching and temporal interpolation policy;
+- native range limits, beam width, beam height, and vertical sampling;
+- quality-mask, clutter, attenuation, range-folding, and dealiasing policy;
+- overlap-resolution and quality-weighting method;
+- treatment of coastlines, terrain, blocked sectors, and missing gates;
+- output format, metadata, and provenance requirements.
+
+Do not combine a Level II moment and a Level III display product merely because
+their names resemble one another. Their processing, resolution, and quality
+semantics must be verified equivalent or the difference must be represented
+explicitly.
+
+## Validate and Align Source Data
+
+Before compositing:
+
+1. verify each site's decoded metadata, time, product, units, and quality;
+2. convert all source fields to one declared projection and common output grid;
+3. align source times using a documented tolerance and interpolation policy;
+4. preserve each source's native spatial support and quality fields;
+5. reject a source that is too stale, out of range, or outside its valid product
+   contract;
+6. label any resampling or interpolation rather than presenting the output as
+   a native-resolution observation.
+
+When a common time cannot be formed without excessive interpolation, use a
+nearest time within the stated tolerance, retain the actual time difference, or
+mark the output unavailable. Do not average distant scans into one pseudo-time
+without showing the temporal support.
+
+## Define the Output Quantity and Quality
+
+For reflectivity, retain dBZ or the product's native calibrated unit and use a
+quality-aware combination rule. Do not average dBZ as a linear physical
+quantity without a stated rationale. For velocity, preserve positive and
+negative radial-velocity conventions and handle dealiasing and folding before
+compositing. For dual-polarization moments, preserve their physical units and
+quality masks.
+
+Keep these fields separate:
+
+- measured or decoded value;
+- quality or suitability score;
+- source site and source time;
+- beam-height or range metadata;
+- interpolation or resampling state;
+- coverage and no-data state.
+
+The output should make it possible to identify which radar contributed each
+pixel, especially near overlap boundaries.
+
+## Select Candidate Data by Quality and Geometry
+
+For each output cell, consider only sources that provide valid coverage at a
+compatible time and product level. A useful selection score can include:
+
+- lower beam height at the target location;
+- shorter range and smaller beam width;
+- fewer terrain or clutter artifacts;
+- better data quality or signal-to-noise status;
+- newer scan or smaller time difference;
+- lower attenuation or range-folding penalty;
+- product-specific suitability such as dual-pol quality.
+
+The score is a modeling choice, not a universal truth. State its terms and
+weights, normalize only comparable components, and test sensitivity to the
+selection rule. Never hide the score behind an unexplained “best radar” rule.
+
+## Resolve Overlaps Deterministically
+
+Use a deterministic rule for every target cell:
+
+1. select the source with the highest declared quality/suitability score;
+2. apply a documented tie-breaker such as lower beam height, smaller range,
+   newer valid time, or stable site order;
+3. preserve the selected source ID and runner-up source; or
+4. use a physics-aware fusion method only after validating it against
+   single-site fields and reference observations.
+
+Do not average dBZ, radial velocity, or quality fields across radars by default.
+Blending is acceptable only with a declared product-specific rationale and
+sensitivity analysis. Never let a blocked, stale, or invalid source win merely
+because its numeric value is larger, larger in magnitude, or easier to
+interpolate.
+
+## Preserve Coverage and Quality Metadata
+
+The mosaic should emit at least:
+
+- value field;
+- source-site field;
+- source-time or time-difference field;
+- beam-height or range-quality field when relevant;
+- quality or suitability field;
+- coverage and no-data mask;
+- product, units, grid, projection, and timestamp metadata.
+
+No-data and masked gates must remain distinguishable from a physical zero or a
+valid low value. A blank-looking region is acceptable only if the coverage mask
+makes its reason visible. Do not fill blocked sectors with neighboring radar
+data without labeling the substitution.
+
+## Handle 3D and Vertical Products
+
+A two-dimensional mosaic must not silently mix elevation sweeps with
+incompatible heights. For reflectivity, state the selected elevation policy
+and range-dependent beam height. For VIL, echo top, or another 3D-derived
+product, use the provider's product definition or a separately validated 3D
+algorithm.
+
+For a vertical composite, retain per-source sweep and beam-height metadata,
+define the vertical target or column, and document the common vertical
+coordinate. Do not call a lowest-sweep composite a column-integrated quantity
+or compare it with a true VIL product without explaining the difference.
+
+## Validate the Mosaic Scientifically
+
+Inspect:
+
+- coverage, holes, overlap seams, and domain edges;
+- discontinuities at site boundaries;
+- implausible values or source-selection flips;
+- range, terrain, and beam-height artifacts;
+- agreement with each source in non-overlap regions;
+- comparison with an independent analysis or observation where available;
+- sensitivity to quality weights, time tolerance, and product choice.
+
+An aesthetically smooth mosaic can hide source disagreements. Preserve the
+unresolved or selected-source map for scientific review. A local composite is
+an analysis with assumptions, not ground truth.
+
+## Coordinate with Analysis and Visualization
+
+Use `radar-satellite-analysis` to interpret storm structure. A separate
+feature-tracking skill may be used after the mosaic when available, but it is
+not required for mosaic construction. Use
+`nexrad-radar-visualization` for site products or decoded gridded products. For
+a constructed mosaic, plot the value alongside source, quality, and coverage
+layers and label it as a local analysis.
+
+For an official NOAA composite, retrieve it with `nexrad-mosaic-access` and
+preserve its product semantics instead of rebuilding it. A custom mosaic can
+be compared with that official product, but the two must not be labeled as
+identical.
+
+## Examples
+
+To combine two overlapping Level II reflectivity volumes, verify both sites,
+sweeps, times, units, and quality; reproject them to a declared grid; then
+select a source per cell using a documented rule based on beam height, range,
+time difference, and quality. Preserve source and coverage arrays beside the
+reflectivity field, and inspect seams and each radar's non-overlap area before
+interpreting the result.
+
+For an MRMS comparison, retrieve the exact official product through
+`nexrad-mosaic-access`, align its valid-time and grid semantics explicitly,
+and report differences as product/algorithm differences rather than treating
+either grid as ground truth.
+
+## Output Contract
+
+Return a custom mosaic with a clear audit trail:
+
+1. source radar sites, product or moment, units, volume times, and quality;
+2. output domain, grid, projection, cell size, and time policy;
+3. source-selection or fusion rule and its parameters;
+4. value, source, quality, beam-height/range, and coverage layers;
+5. rejected sources and cells with reasons;
+6. validation results and sensitivity to major construction choices;
+7. scientific limitations and distinction from official MRMS products; and
+8. provenance and checksums for inputs, code, configuration, and outputs.
+
+Do not publish only a colored mosaic. The source, quality, and coverage layers
+are part of the result whenever overlap or heterogeneous radar support matters.
+
+## Verification Checklist
+
+- Every source product, site, unit, and time is verified before compositing.
+- The common time, grid, projection, and range policy are explicit.
+- Level II and Level III products are not treated as interchangeable.
+- Quality, terrain, beam height, range folding, and de-aliasing checks are
+  applied.
+- Overlap selection is deterministic, auditable, and sensitivity-tested.
+- No-data, blocked sectors, and source substitutions remain visible.
+- Source, quality, and coverage metadata accompany the value field.
+- Custom output is labeled as a local analysis, not an official MRMS product.
+
+## Security & Safety Notes
+
+- Use public or authorized radar data only.
+- Do not expose cloud credentials, signed URLs, private bucket names, or
+  sensitive station metadata in outputs or logs.
+- Treat metadata, source IDs, and product names as untrusted input; validate
+  paths and labels before rendering.
+- Bound site count, volume size, output extent, interpolation, and worker count.
+- Preserve NOAA, NEXRAD, Unidata, and other provider attribution and license
+  terms.
+
+## Common Pitfalls
+
+- **Seams appeared at radar boundaries:** Source selection or quality weights
+  were not declared. Preserve source and quality layers and test tie-breaks.
+- **dBZ was averaged across sites:** A logarithmic reflectivity quantity was
+  treated as a linear scalar. Use a product-specific rule and sensitivity.
+- **A blocked sector looked like no rain:** No-data or quality-masked gates were
+  converted to zero. Preserve the coverage mask.
+- **A lower sweep was compared with a 3D product:** The vertical meaning was
+  collapsed. State the elevation and product definition.
+- **The composite changed between runs:** Site order, time tolerance, or random
+  sampling determined the winner. Make selection deterministic and record its
+  parameters.
+- **A custom mosaic was called official:** The local product was confused with
+  NOAA MRMS. Keep source and algorithm identity in the output metadata.
+
+## Limitations
+
+- Heterogeneous range, beam width, terrain, calibration, and product processing
+  limit cross-site comparability.
+- A selection-based mosaic may create discontinuities or discard useful
+  information from a second radar.
+- No pixel is an independent observation; quality and source fields are
+  correlated in space and time.
+- Custom mosaics require local validation and are not an official warning or
+  truth product.
+
+## Additional Resources
+
+- [NEXRAD on the AWS Registry of Open Data](https://registry.opendata.aws/noaa-nexrad/)
+- [NOAA MRMS 2D product directory](https://mrms.ncep.noaa.gov/2D/)
+- [NOAA Radar Operations Center interface documents](https://www.roc.noaa.gov/wsr88d/BuildInfo/Files.aspx)

package/bundled-skills/nexrad-product-access/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: nexrad-product-access
+description: "Discover and access NEXRAD data for a selected radar site, time, product, or Level II moment using completed archive volumes, real-time chunks, or supported Level III sources with metadata validation."
+category: data
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-25"
+author: ShianMike
+tags: [weather, nexrad, level-ii, level-iii, radar-products, single-site, aws-s3]
+tools: [claude, cursor, gemini, codex]
+---
+
+# NEXRAD Product Access
+
+## Overview
+
+Select and retrieve the correct NEXRAD data for one radar site, UTC time, and
+requested product or Level II moment. Keep archive volumes, real-time chunks,
+and Level III products distinct because they have different availability and
+decoding contracts.
+
+Use `noaa-radar-satellite-fetching` for common NOAA archive discovery and
+download mechanics when that skill is available. This skill provides the
+NEXRAD-specific Level II/III selection contract. Use
+`nexrad-mosaic-access` when the requested result is a precomputed multi-radar
+composite rather than one site's data.
+
+## When to Use This Skill
+
+- Fetch a completed NEXRAD Level II volume from the historical archive.
+- Follow or assemble real-time Level II chunks for a named site.
+- Retrieve selected real-time Level III products or use an operational Level
+  III feed.
+- Select a product such as reflectivity, velocity, spectrum width, echo top,
+  vertically integrated liquid, or a supported dual-polarization product.
+- Select a particular Level II moment, elevation sweep, or volume interval.
+- Restrict access to one radar site and reject composite or neighboring-site
+  data.
+
+Do not turn a Level II moment name into a Level III product code by assumption.
+The two levels have different processing and distribution contracts.
+
+## Current Public NEXRAD Resources
+
+The current NEXRAD-on-AWS registry documents these public resources in
+`us-east-1`:
+
+| Need | Resource | Contract |
+| --- | --- | --- |
+| Historical completed Level II volumes | `s3://unidata-nexrad-level2/` | Archive volumes organized by UTC date and site. |
+| Real-time Level II chunks | `s3://unidata-nexrad-level2-chunks/` | Chunks that must be assembled and validated as volumes. |
+| Selected real-time Level III data | `s3://unidata-nexrad-level3/` | Selected Level III products, not a promise of a complete historical archive. |
+
+Unidata documentation also describes operational Level III distribution through
+the `NEXRAD3` LDM/NOAAPort feed. Resolve the current source for the requested
+Level III product instead of assuming that a real-time S3 bucket is a complete
+archive.
+
+The current AWS registry identifies `unidata-nexrad-level2` as the archive and
+says the former `noaa-nexrad-level2` bucket was deprecated after September 1,
+2025. Verify the live registry before access because provider resources can
+change.
+
+## Define the Access Contract
+
+Resolve and record:
+
+- one four-character NEXRAD site such as `KTLX`;
+- the requested instant or bounded interval in UTC;
+- nearest-at-or-before, nearest-in-either-direction, or interval-overlap policy;
+- data level: Level II, Level III, or an explicitly mixed workflow;
+- product or moment, unit, sweep or scan angle, and whether all sweeps or the
+  lowest requested sweep are needed;
+- archive, real-time, or operational-feed source;
+- maximum lookback, maximum probes, and acceptable latency;
+- required metadata, quality masks, and output form;
+- whether the product must come from that one site only.
+
+If the user supplies only a display concept such as “base reflectivity,”
+resolve it against a current official product or Level II moment definition.
+Do not guess a Level III code or claim that every named display is available in
+the same feed.
+
+## Access Historical Level II Volumes
+
+1. Validate the site against an allowlist or a current NEXRAD site inventory.
+2. Resolve the exact UTC day and site prefix from current dataset
+   documentation. Do not infer the key layout from a filename example.
+3. List only that documented prefix, paginating within a bounded key count.
+4. Parse the documented volume timestamp and site from each candidate key.
+5. Select by the time policy, then request metadata for the exact key.
+6. Require a nonzero stable object. If publication may still be occurring,
+   repeat the metadata check until size and object identity remain unchanged.
+7. Download to a temporary path, verify received bytes, compute a local
+   SHA-256 when provenance requires it, and open with a format-aware reader.
+8. Verify the decoded site, volume start/end time, sweeps, moments, dimensions,
+   and quality fields before promoting the file into a valid cache entry.
+
+The archive is the preferred source for retrospective work because each object
+is a completed volume. Do not substitute a real-time chunk for an archive volume
+when the consumer expects a self-contained volume.
+
+## Access Real-Time Level II Chunks
+
+Treat each chunk as a fragment with ordering and completion dependencies.
+
+1. Resolve the current chunk prefix for the requested site.
+2. Parse volume and chunk identity from documented key fields.
+3. Discover the complete chunk sequence with a bounded lookback.
+4. Verify required chunks, byte identities, and scan metadata.
+5. Assemble into a new temporary file without overwriting the source chunks.
+6. Decode the assembled object and verify site, volume time, sweep count,
+   moments, and quality fields.
+7. Publish the verified volume atomically and record which chunks formed it.
+
+If a chunk is late, duplicated, discontinuous, or from another site, reject or
+quarantine the sequence. A file that opens without proving complete volume
+metadata is not a verified replacement for an archive volume.
+
+## Select Level II Moments and Sweeps
+
+Level II exposes moments within a volume rather than independent Level III
+display products. Depending on the radar configuration and volume, common
+moments can include reflectivity, velocity, spectrum width, and supported
+dual-polarization quantities.
+
+Before extraction, record:
+
+- the exact moment name used by the decoded file;
+- its calibrated physical unit and scale or offset;
+- the elevation-angle policy and actual beam height at the display range;
+- the quality fields for range folding, clutter, dealiasing, or invalid gates;
+- whether the output requires all sweeps, a nearest sweep, or a sweep search
+  based on target height.
+
+Do not assume that a moment is present in every volume or at every sweep.
+Report an absent moment or incomplete sweep rather than converting a different
+moment into its place.
+
+## Access Level III Products
+
+Level III is a processed radar product with its own product code, scan strategy,
+projection, resolution, and update cadence. Resolve the official current code
+and source for the requested semantic product.
+
+For selected real-time data, inspect only the documented Level III prefix for
+the site and time window. For broader operational access, use a current LDM or
+NOAAPort product feed that explicitly carries the requested NEXRAD3 product.
+
+After retrieval, verify:
+
+- site or coverage area;
+- product code and product description;
+- observation or scan time;
+- projection, dimensions, and data level;
+- units, scale/offset, missing values, and quality flags;
+- whether the product is a single-site, sector, or multi-site product.
+
+Never decode a Level III file using a Level II volume contract. Never label a
+single-site Level III product as a mosaic merely because several scans or pixels
+are present.
+
+## Examples
+
+For a request such as “Get the latest completed KTLX Level II volume before
+2026-09-25 12:00 UTC,” state the site, cutoff, selection policy, archive
+source, and selected volume time. Retrieve that exact object, then confirm the
+decoded volume reports KTLX and the expected scan interval before handing it
+to a plotting or analysis step.
+
+For “KTLX base reflectivity,” resolve whether the request means the Level II
+reflectivity moment or a Level III processed product. Report the chosen level,
+moment/product identifier, sweep, units, and observed scan time.
+
+## Return an Access Record
+
+Return a structured record before decoding begins:
+
+```json
+{
+  "site": "KTLX",
+  "requested_time_utc": "2026-09-25T12:00:00Z",
+  "selection_policy": "nearest-at-or-before",
+  "selected_time_utc": "2026-09-25T11:59:54Z",
+  "data_level": "Level II",
+  "product_or_moment": "REF",
+  "source": "s3://unidata-nexrad-level2/EXACT_DOCUMENTED_KEY",
+  "object_identity": {
+    "etag": "OPAQUE_IDENTITY",
+    "last_modified": "2026-09-25T12:01:02Z",
+    "size_bytes": 12345678
+  },
+  "single_site_required": true
+}
+```
+
+Also record rejected candidates, unavailable products, chunk dependencies, and
+the rule that prevented cross-site or cross-product substitution.
+
+## Verification Checklist
+
+- The four-character site and site inventory entry are validated.
+- All timestamps are UTC and the scan-selection policy is explicit.
+- The source matches the requested level and product or moment.
+- Historical access uses completed Level II archive volumes when appropriate.
+- Real-time chunks are assembled into a verified complete volume.
+- Level III products are resolved through a documented current source.
+- Decoded metadata confirms site, time, product, dimensions, and quality fields.
+- No result from another site or product is silently substituted.
+- Source identity, local hash, and retrieval time are recorded when required.
+
+## Security & Safety Notes
+
+- Use public or authorized NEXRAD resources only.
+- Do not embed cloud credentials, signed URLs, tokens, or private endpoint
+  details in records or logs.
+- Treat site identifiers, product names, metadata, and object keys as untrusted
+  input when constructing paths or commands.
+- Bound prefix width, pagination, time lookback, response size, concurrency, and
+  disk use.
+- Preserve NOAA, NEXRAD, Unidata, and source-provider attribution and license
+  terms.
+
+## Common Pitfalls
+
+- **The old bucket returned no data:** A tutorial used the deprecated
+  `noaa-nexrad-level2` route. Resolve the current archive from the live AWS
+  registry.
+- **A real-time file would not decode:** Individual chunks were treated as a
+  completed volume. Assemble and validate the full sequence first.
+- **The product selector guessed the wrong item:** A display name was converted
+  to an assumed Level III code. Resolve a current official product definition.
+- **A reflectivity request returned velocity:** Product or moment identity was
+  not carried through decoding and extraction.
+- **The latest run was silently older:** Candidate time and tolerance were not
+  recorded. Return the selected time and rejected candidates.
+- **Data from a neighboring radar appeared:** A regional key search ignored the
+  single-site contract. Filter and validate by exact site identity.
+
+## Limitations
+
+- Availability, feed contents, product definitions, and archive retention can
+  change. Verify current official documentation.
+- The selected real-time Level III resource is not a complete historical
+  archive contract.
+- Accessing a file does not prove that its coverage is scientifically suitable
+  at a requested location; beam height, terrain, range, and quality still matter.
+- Multi-radar composite access belongs in `nexrad-mosaic-access`.
+- Scientific interpretation belongs in `radar-satellite-analysis`.
+
+## Additional Resources
+
+- [NEXRAD on the AWS Registry of Open Data](https://registry.opendata.aws/noaa-nexrad/)
+- [NOAA ROC Level II data types](https://www.roc.noaa.gov/level-two-data-types.php)
+- [NOAA ROC Level III data types](https://www.roc.noaa.gov/level-three-data-types.php)
+- [Unidata LDM feeds](https://unidata.github.io/awips2/edex/ldm/)
+- [Unidata GEMPAK NIDS products](https://unidata.github.io/gempak/man/prog/gpnids.html)