opencode-skills-collection 4.0.73 → 4.0.75

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)

package/bundled-skills/nexrad-radar-visualization/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: nexrad-radar-visualization
+description: "Plot NEXRAD Level II/III site scans and decoded radar mosaics with correct radar geometry, map grids, units, quality masks, timestamps, and provenance."
+category: analysis
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-25"
+author: ShianMike
+tags: [weather, nexrad, radar-plotting, ppi, velocity, dual-pol, cross-section, visualization]
+tools: [claude, cursor, gemini, codex]
+---
+
+# NEXRAD Radar Visualization
+
+## Overview
+
+Create scientifically legible plots from verified NEXRAD single-site products
+and decoded radar mosaics. Preserve site or domain, product, observation or
+valid time, units, geometry, quality masking, and color meaning so a visually
+compelling image cannot hide a wrong quantity or misleading spatial
+interpretation.
+
+Use this skill after `nexrad-product-access` or another trusted source has
+provided a decoded site product. Use `nexrad-mosaic-access` to retrieve an
+official MRMS composite before plotting it. This skill does not discover or
+download radar files.
+
+## When to Use This Skill
+
+- Plot base reflectivity, radial velocity, spectrum width, or another decoded
+  Level II moment for one NEXRAD site.
+- Plot a Level III product selected by product code and scan time.
+- Plot a decoded NOAA/NCEP MRMS or other documented NEXRAD-derived gridded
+  composite while preserving its grid, coverage, and product semantics.
+- Create a lowest-elevation PPI, a specified-elevation PPI, or a sweep chosen
+  for a target height.
+- Plot dual-polarization moments with appropriate units and masks.
+- Create RHI, cross-section, tilt, storm-relative, or multi-sweep views.
+- Build a time sequence or animation from a verified scan series.
+- Export the plot with a stable color scale, map context, metadata, and
+  provenance.
+
+Do not use a plot to hide a missing sweep, unverified product, invalid gate mask,
+geolocation error, or unsupported extrapolation.
+
+## Define the Visualization Contract
+
+Record:
+
+- radar site and site coordinates;
+- data level and exact product or moment;
+- observation, volume, or product time in UTC;
+- source identity and local content hash when required;
+- intended view: PPI, RHI, cross-section, tilt, comparison, or animation;
+- sweep or angle policy;
+- map projection, bounds, range rings, and landmark context;
+- physical units, color scale, display range, and normalization policy;
+- invalid, missing, folded, clutter, or otherwise masked gates;
+- for gridded mosaics, the provider, product/domain, grid projection and
+  orientation, valid-time semantics, and source/coverage or quality fields;
+- output format, dimensions, background, and whether figures are for analysis or
+  publication.
+
+If the user asks only for “a radar image,” produce a useful default: a
+single-site PPI with site marker, UTC time, product, units, color bar, range
+rings, and missing-data treatment visible. For a decoded mosaic, use a map view
+with the product, domain, valid time, units, legend, and missing-data treatment
+visible. Ask only when product, site/domain, or time would materially change
+the result and cannot be inferred safely.
+
+## Validate Before Plotting
+
+1. Confirm the decoded site, product or moment, time, units, dimensions, and
+   projection.
+2. Apply scale, offset, calibration, fill values, and quality flags before
+   interpolation, contouring, or thresholding.
+3. Confirm that the requested sweep exists. For a target-height sweep, compute
+   or obtain beam height as a function of range and show which elevation is
+   nearest.
+4. Preserve no-data and invalid-data cells as masked values. Do not replace them
+   with zero, minimum reflectivity, or an opaque background that resembles weak
+   echo.
+5. Confirm that map coordinates and radar polar coordinates share the correct
+   projection and origin.
+6. Record whether velocity is dealiased and whether dual-polarization fields have
+   their documented quality masks.
+
+## Plot a PPI
+
+For a plan-position indicator:
+
+1. Select the requested sweep or the lowest usable sweep under a stated policy.
+2. Convert range and azimuth to the selected map projection.
+3. Mask invalid, below-threshold display, folded, clutter-contaminated, and
+   missing gates according to an explicit policy.
+4. Render the measured product with a documented, perceptually ordered color
+   scale appropriate to the quantity.
+5. Overlay radar location, requested site label, range rings or distance scale,
+   north arrow when orientation could be ambiguous, and optional geographic
+   context.
+6. Put product, site, UTC time, units, sweep or product code, range, and color bar
+   in the figure itself.
+
+For reflectivity, do not imply that every dBZ color boundary is a categorical
+precipitation type. Keep the measured reflectivity label visible and put any
+rain-rate relation in a separate, explicitly derived layer.
+
+For velocity, use a diverging scale centered on zero unless the product's
+documented semantics require another convention. Radial velocity points toward
+or away from the radar according to the data convention; it is not a full wind
+vector. Do not draw environmental wind arrows from radial velocity without an
+explicit deconvolution or retrieval method.
+
+## Plot Dual-Polarization Moments
+
+Preserve the physical unit for each field, such as differential reflectivity in
+dB, differential phase in degrees, correlation coefficient as a unitless
+quantity, and specific differential phase with its documented units and scale.
+
+Keep raw dual-polarization fields separate from hydrometeor classification. If a
+classification is displayed, state the input moments, thresholds, quality
+masking, and whether the classification is measured, retrieved, or heuristic.
+
+Do not normalize each sweep independently before an animation or comparison;
+that can make a changing storm look stationary. Use one declared scale for the
+whole sequence unless a separate panel is explicitly labeled.
+
+## Choose a Sweep for a Target
+
+Lowest-level products emphasize near-surface structure but are vulnerable to
+terrain, clutter, biological targets, and beam broadening. Higher sweeps sample
+different heights and can miss low-level features.
+
+When selecting a sweep by target height:
+
+1. use the radar elevation angles and a documented beam-height relationship;
+2. solve for the nearest sweep at the requested range and height;
+3. label the selected elevation and estimated sampling height;
+4. show the choice on a vertical cross-section when the selection is material.
+
+Do not call the lowest sweep a surface observation. Its beam samples a volume
+whose center height varies with range and whose width increases away from the
+radar.
+
+## Plot RHI, Cross-Sections, and Tilts
+
+An RHI or cross-section is a derived view assembled from multiple sweeps or
+volumes. Preserve source volume identity, azimuth or line orientation,
+horizontal-distance coordinate, vertical coordinate, interpolation method, and
+beam-height geometry.
+
+Do not connect gates across large angular gaps, missing sweeps, or incompatible
+volumes without showing the gap. Avoid implying sub-beam vertical resolution.
+For a storm tilt sequence, use the same cross-section line or documented tracking
+logic across times and show how the line moves.
+
+## Create Time Sequences
+
+For an animation or loop:
+
+- use a verified chronological scan sequence;
+- preserve the requested cadence and mark skipped or duplicated scans;
+- keep site, product, color scale, map bounds, and range constant;
+- show UTC time on every frame or in a clearly visible persistent timestamp;
+- do not duplicate a stale frame to fill a gap without labeling the hold;
+- stop at the last verified frame when the stream ends.
+
+An animation is not evidence of temporal evolution unless frames are aligned,
+correctly timed, and generated from the same product and projection.
+
+## Plot a Precomputed Mosaic
+
+For an MRMS or other decoded NEXRAD-derived grid:
+
+1. Verify product identity, domain, valid or accumulation time, units, grid
+   projection, dimensions, coordinate orientation, and decoded extent.
+2. Apply the product's scale, offset, fill values, quality flags, and coverage
+   mask before rendering. Preserve missing coverage as missing; do not turn it
+   into zero-valued precipitation or reflectivity.
+3. Render the documented geographic extent and coordinate grid. Reproject only
+   with an explicit transformation and retain the native grid metadata.
+4. Label the exact product, provider, domain, valid-time interval, units, and
+   color scale. Show coverage or source attribution when supplied with the
+   decoded data.
+5. Keep official provider products distinct from locally constructed mosaics;
+   use `nexrad-mosaic-construction` for construction and label its output as a
+   local analysis.
+
+Do not apply single-radar azimuth/range geometry or sweep labels to an MRMS
+grid. Do not claim a mosaic represents every native radar moment or elevation.
+
+## Design the Figure
+
+Use the minimum visual elements needed to interpret the measurement:
+
+- product and unit;
+- site or mosaic domain and UTC/valid time;
+- sweep, angle, or product code;
+- color bar with fixed limits and an explicit missing-data color;
+- radar location and range context for site plots, or geographic extent and
+  orientation for gridded plots;
+- relevant masks or quality annotation;
+- source and processing note when the figure leaves the controlled environment.
+
+Avoid decorative terrain or boundaries that obscure gates, imply high
+resolution, or dominate the measured field. Do not crop away the radar site,
+range rings, or color bar without replacing the lost context.
+
+For a multi-panel figure, label each panel by product and time and state whether
+the panels share a scale. Use consistent geometry across panels so a viewer can
+compare evolution without reorienting the scene.
+
+## Examples
+
+Given a decoded KTLX volume, render the lowest usable reflectivity sweep with
+the site, Level II moment, observed UTC time, dBZ units, color bar, range rings,
+and invalid gates visibly masked. Read the timestamp and product metadata from
+the volume rather than inventing them.
+
+When comparing two velocity scans, first verify they are from the same site,
+product, units, and sweep policy. Use one shared diverging color scale, show
+each scan's actual UTC time, and leave missing gates masked rather than filling
+them with zero velocity.
+
+When plotting an MRMS composite, retrieve the exact product and timestamp with
+`nexrad-mosaic-access`, validate its native grid and valid-time semantics, and
+show its provider, domain, units, legend, and missing-data mask. Do not apply
+single-site sweep geometry or present the composite as a custom mosaic.
+
+## Export and Verify
+
+For static output, verify the actual rendered file—not only the plotting call.
+Open or inspect the image and confirm:
+
+- nonblank data and expected radar coverage;
+- correct orientation and site position;
+- readable labels, units, timestamp, and color bar;
+- no clipped legends or accidental all-background panels;
+- correct color limits and no unintended missing-data substitution;
+- aspect ratio that does not distort distance;
+- file format, dimensions, and checksum for publication workflows.
+
+For interactive output, also test zoom, time selection, product switching, and
+the behavior when a sweep or scan is unavailable.
+
+Record the plotting-library versions, projection, transformations, display
+limits, masks, output path, and input identity. Pair the figure with
+`weather-data-reproducibility` when it must be regenerated later.
+
+## Output Contract
+
+Return or publish:
+
+1. the requested image, animation, or interactive view;
+2. the exact site or mosaic domain, provider, product or moment, sweep if
+   applicable, and UTC/valid time shown;
+3. units, color range, missing-data policy, and quality masks;
+4. projection, native grid or beam/sampling geometry, and processing
+   transformations;
+5. verified output path or attachment and its media type;
+6. limitations that materially affect interpretation.
+
+Do not return a plot without enough metadata for another analyst to understand
+what is being displayed.
+
+## Verification Checklist
+
+- Site, product, moment, time, and sweep are verified from decoded metadata.
+- Units, calibration, scale/offset, and missing values are applied correctly.
+- PPI geometry uses the radar location and correct projection.
+- Velocity uses a meaningful diverging scale and is labeled radial.
+- Sweep selection states the elevation and target or beam height.
+- Cross-sections disclose interpolation and source volumes.
+- Animation frames are ordered, aligned, and consistently scaled.
+- Invalid gates are masked rather than plotted as real weak echo.
+- The rendered artifact was visually inspected after export.
+
+## Security & Safety Notes
+
+- Plot only public or authorized radar products.
+- Do not expose credentials, signed URLs, private bucket names, or sensitive
+  station details in images or logs.
+- Treat metadata and product names as untrusted input; escape labels and use
+  controlled output paths.
+- Bound image dimensions, animation frame count, interpolation work, and memory
+  use.
+- Preserve provider attribution and do not imply NOAA endorsement.
+
+## Common Pitfalls
+
+- **The reflectivity map is displaced:** Fixed display coordinates or the wrong
+  radar origin were used. Reproject the polar data explicitly.
+- **Velocity colors imply storm motion:** Diverging radial velocity was
+  interpreted as a full wind vector. Label the quantity as radial velocity.
+- **The animation flickered between storms:** Every sweep was independently
+  normalized. Use one fixed scale across verified frames.
+- **Missing gates appeared as weak echoes:** No-data values were plotted as the
+  minimum color. Mask them and show a distinct background.
+- **The lowest sweep was called surface data:** Range-dependent beam height was
+  ignored. State the beam geometry and sampling height.
+- **A cross-section invented vertical detail:** Sparse sweeps were smoothly
+  interpolated without gaps. Preserve resolution limits and missing sectors.
+
+## Limitations
+
+- Radar plots display remote-sensing observations and processed products, not
+  direct surface truth.
+- Display quality cannot repair terrain blockage, attenuation, calibration
+  problems, or a wrong product selection.
+- A static image cannot establish future motion or storm behavior.
+- This skill does not fetch data, construct mosaics, or replace scientific
+  interpretation and verification.
+
+## Additional Resources
+
+- [NOAA ROC Level II data types](https://www.roc.noaa.gov/level-two-data-types.php)
+- [NEXRAD on the AWS Registry of Open Data](https://registry.opendata.aws/noaa-nexrad/)