Skip to main content

METHOD / SOURCE CONTRACTS

How the brief is built.

Don't Die Fishing assembles public forecasts, observations, tide products, and cited regulation references into a compact planning view. The sections below describe the current contracts in the app; they do not grant permission to launch, navigate, or fish.

01 / SOURCE ROLES

Each source has a different job.

NWS supplies the forecast and active-alert inputs. DDF uses its point, forecast, hourly, grid, and alert paths for forecast wind, gusts, air temperature, precipitation, visibility inference, lightning inference, marine warnings, and the site time zone.

NOAA / NDBC supplies configured buoy observations. When a usable observation is available, it contributes observed wind, gusts, wave height, wave period, swell direction, and water temperature.

NOAA CO-OPS supplies configured station tide predictions, water temperature, and tidal-current predictions. EPA supplies the UV Index input; it is an outdoor-exposure planning signal, not a marine forecast.

Forecast data and regulation authority stay separate: public weather and water products inform the planning view, while the applicable state agency, code, and in-season action control fishing rules.

SOURCES NWS marine forecasts and warnings ↗, NOAA / NDBC observations ↗, NOAA CO-OPS products ↗, EPA UV Index ↗HOW WE APPLY IT the conditions aggregator combines source fetches into a condition snapshot

02 / UNITS + TIME

The display normalizes units, not authority.

Condition snapshots use knots for wind and current, feet for waves and tide height, miles for visibility, seconds for wave period, Fahrenheit for temperature, percent for precipitation probability, and the unitless EPA UV Index. Source-specific conversions happen at the fetch boundary so the scorer receives one consistent shape.

Source timestamps are not silently treated as one clock. NDBC observations are read as UTC; NWS forecast intervals carry their own time-zone metadata and offsets; CO-OPS products are requested with an explicit time-zone mode; and EPA UV rows are matched to local solar time using the site longitude. Site-local display times use the stored or resolved IANA time zone when one is available.

SOURCES NDBC measurement descriptions ↗, NWS API documentation ↗, IANA time-zone database ↗HOW WE APPLY IT the shared data definitions defines shared condition, vessel, and profile shapes, the conditions aggregator combines source fetches into a condition snapshot

03 / FRESHNESS

Age and malformed timestamps fail closed.

A configured NDBC observation older than three hours, or dated more than fifteen minutes in the future, is treated as unavailable. NWS grid values must cover the current instant and pass strict timestamp and unit checks; otherwise that optional forecast signal is omitted. These are data-quality gates, not guarantees about future conditions.

The aggregate snapshot is stamped when the fetch completes, but that stamp does not make every source equally fresh. Public landing derivations accept only a bounded, non-future snapshot: its fetched_at must be no more than six hours old and no more than fifteen minutes in the future. An unavailable or malformed snapshot keeps the branded unavailable/illustrative state instead of displaying a made-up reading.

Regulation freshness is a separate contract: a normalized rule needs a recent source check, the applicable effective year, a valid site time zone, complete provenance, and non-ambiguous season windows before DDF describes a current status. Older or incomplete rows remain references to verify, not current authority.

SOURCES NOAA / NDBC observations ↗, NWS marine forecasts and warnings ↗, NOAA CO-OPS products ↗HOW WE APPLY IT the buoy reader parses and freshness-checks NDBC observations, the forecast reader parses NWS forecast and alert data, the homepage live-data guard guards public landing-page live derivations, the conditions aggregator combines source fetches into a condition snapshot

04 / SCORING

The score is deterministic planning guidance.

DDF computes a 0–100 adverse-condition score for the selected vessel and profile. Lower is more favorable under that configuration: scores below 40 map to GO, 40–59 map to CAUTION, and 60–100 map to NO-GO. Those bands are DDF display thresholds, not official operating limits.

Hard vetoes run before weighted scoring. The current veto contract covers configured severe marine-warning phrases, high lightning risk, and extreme profile-relative readings: wind, gusts, waves, or current above 1.5× the selected threshold, visibility below 0.5×, or water temperature below 0.75×. A veto returns NO-GO/100 with a reason; it is still advisory and does not replace an official warning or judgment. A veto or limit can only fire on a reading that exists: when no water temperature is available, the verdict says the water temperature limit could not be checked, rather than counting it as passed.

Coast Guard bar status is a veto with a size. Under 33 CFR 165.1325 a bar restriction prohibits recreational and uninspected passenger vessels from crossing; Coast Guard guidance states each restriction for vessels of a given length, covering vessels of that length or less. A restriction read as “Recreational: 40 FOOT” vetoes a vessel of 40 ft or less and any vessel whose length is not set, while a longer vessel keeps the entry as a watch-level warning and the verdict is held at CAUTION or worse. Restrictions stated as “ALL”, unreadable scopes, and Captain of the Port closures veto every vessel.

Marine alerts are read for the launch point and for the marine zones around it. A launch pin usually sits on land, so each curated launch also checks its home zones: the National Weather Service marine zones for the water it sits on. These are the nearshore zones within 3.25 nautical miles of the pin, or the nearest one within 10 nautical miles if none is that close, with reviewed corrections where that rule picks up water across land or past an entrance. An advisory in a home zone vetoes like any other.

Some curated launches also check route zones. These are reviewed by hand: water you cross to go beyond the launch, such as the ocean outside the Golden Gate for San Francisco Bay launches. An advisory there is shown with where it applies, for example “Outside the Golden Gate: Small Craft Advisory”. It holds the day at CAUTION or worse, but it does not force NO-GO by itself. A monitored trip is never marked good to go while it is in force. Other zones are not checked, so plan your own route past the water listed here. A custom launch site uses no zone table. It is checked at its point, plus the bar zones when it shares a bar port’s name.

A failed marine alert check is an unknown, not a clear. When a National Weather Service alert lookup or the Coast Guard bar status lookup does not complete, the snapshot records the check as incomplete: that entry scores like an unclassified advisory, never vetoes, and holds the total at 40 so the current verdict reads CAUTION or worse, never GO. A total already above 40 is unchanged. Forecast cells have no alert input and are not held.

Available signals are weighted by the selected profile. A missing numeric signal is not turned into a favorable zero: it is marked unavailable, excluded from the weighted total, and the remaining available weights are renormalized. A missing warning array is not silently treated as “no warnings” in the landing live-data guard.

Waves are scored on steepness, not height alone. Each reading with a dominant period is classified with the NDBC steepness algorithm (significant height in metres against period3.3 ÷ 250, 500 and 1000 for very steep, steep and average; a reading under the average line is swell when its period is 10 s or more, otherwise average). A steep sea is scored as 1.25× and a very steep sea as 1.5× its measured height against the vessel wave limit, so 5 ft at 7 s meets a 6 ft limit while 5 ft at 14 s does not. The method follows the NWS Western Region hazardous-seas criteria; the 1.25× and 1.5× factors are DDF calibration, and the hard veto still uses the measured height. Readings under 1 ft or with a period under 2 s (below the NDBC spectral band) are not classified. Fair-weather odds remain height-only.

A vessel can also set an optional minimum wave period, off by default. On a reading of 1 ft or more with a dominant period shorter than that setting, the day is held at CAUTION or worse and the reason names the period, unless two other limits are already past; it never vetoes a trip by itself, and it does not change the steepness scoring above. If the period is missing or under 2 s the verdict line and the pre-trip brief say the limit could not be checked, rather than passed. It reads dominant period only, so short chop under a longer swell is not seen, and forecast days carry no period, so it applies to live conditions only.

WAVE STEEPNESS CALIBRATION

NDBC steepness classification applied to effective wave height (hard 1.5× veto still uses raw measured height).

SWELL / AVERAGE1.00× measured height
STEEP (T³·³ / 500)1.25× measured height
VERY STEEP (T³·³ / 250)1.50× measured height

MODERATE PROFILE WEIGHTS

Baseline signal weights before missing-data renormalization.

Wind & Gusts
20%
Waves & Steepness
18%
Marine Warnings
15%
Visibility
12%
Tidal Currents
10%
Lightning Risk
8%
Precip / Water Qual / UV / Temp / Travel
17%
SOURCES NWS marine forecasts and warnings ↗, NDBC wave steepness calculation ↗, NWS WR TA 03-11: steepness-based hazardous seas ↗HOW WE APPLY IT the shared scoring library applies profile-aware adverse-condition scoring, the vessel threshold table defines vessel and profile threshold defaults, the hard-stop rules defines hard NO-GO conditions

05 / VESSEL PROFILES

The vessel changes the lens.

The shared contract supports powerboat, sailboat, kayak, and paddleboard vessel types, with cautious, moderate, and experienced scoring profiles. Vessel type selects the default threshold set; scoring profile selects the default weighting posture. A saved vessel may also carry custom thresholds and weights.

“Cautious,” “moderate,” and “experienced” are configuration labels, not a certification of a person, vessel, or route. Choose the profile that reflects the actual craft, crew, and conditions, then compare the brief with official products and your own judgment.

DEFAULT VESSEL OPERATING THRESHOLDS

Baseline limits per hull class before custom per-vessel overrides (sustained wind, gusts, wave height, visibility, current, and cold-water floor; custom profiles can also set a minimum wave period floor).

Hull ClassWindGustWavesVisCurrentCold FloorLightning
Powerboat25 kt35 kt6 ft1.0 mi4 kt45 °FModerate
Sailboat30 kt40 kt8 ft1.0 mi4 kt45 °FModerate
Kayak15 kt20 kt2 ft0.5 mi2 kt55 °FLow
Paddleboard15 kt20 kt2 ft0.5 mi2 kt55 °FLow
SOURCE U.S. Coast Guard recreational boating resources ↗HOW WE APPLY IT the shared data definitions defines shared condition, vessel, and profile shapes, the vessel threshold table defines vessel and profile threshold defaults, the signal weighting profiles defines signal weighting profiles

06 / MISSING DATA

Unavailable is an honest result.

Fetch failures, invalid values, stale observations, and missing optional fields resolve to null or an explicit unavailable result at the boundary. The interface uses labels such as “N/A,” “unavailable,” or “verify official rules” instead of inventing zeroes, substituting an unrelated reading, or presenting an empty warning response as proof of calm conditions.

Forecast-only planning windows are labeled as forecast data and do not imply that unforecast waves, tides, currents, water temperature, or UV values were observed. Current conditions and forward-looking forecasts are different evidence classes.

SOURCES NWS marine forecasts and warnings ↗, NOAA / NDBC observations ↗, NOAA CO-OPS products ↗, EPA UV Index ↗HOW WE APPLY IT the conditions aggregator combines source fetches into a condition snapshot, the shared scoring library applies profile-aware adverse-condition scoring

07 / REGULATION PROVENANCE

Rules are references, not permission.

Regulation rows are kept separate from the conditions score. A normalized row can be evaluated only when it has a source URL, authority, source-updated date, source-check timestamp, matching effective year, valid IANA site time zone, and valid, non-overlapping season windows. The shared freshness window is seven days.

Legacy rows are retained as reference-only material and never authorize a current open/closed status. DDF links the cited state or federal source beside a listing and tells the reader to verify the applicable official rule, code, emergency order, and in-season action before fishing or retaining a catch.

The regulation catalog is therefore a sourced index of what DDF has recorded, not a complete rulebook and not legal permission. The public catalog exposes the source and its freshness context for each supported jurisdiction.

SOURCE Example state regulation source: Massachusetts DMF ↗HOW WE APPLY IT the regulations evaluator normalizes and evaluates regulation rows

08 / CONFIDENCE + BOUNDARY

No numeric confidence is implied.

DDF does not currently publish a statistical confidence score or probability. GO, CAUTION, and NO-GO are deterministic labels from the selected profile and the signals that passed their data-quality gates; they do not mean “safe,” guaranteed, complete, or authorized.

Missing data reduces what can be evaluated; it is not evidence that the remaining data is more reliable. Read the source timestamps, inspect the official forecast and warnings, verify the applicable regulations, and apply professional maritime judgment before and during a trip.

This product is a planning aid. It is not emergency dispatch, a navigation service, a safety authorization, a legal decision, or a substitute for official weather, marine warnings, navigational notices, local regulations, or qualified judgment.

SOURCE NWS marine forecasts and warnings ↗HOW WE APPLY IT the shared scoring library applies profile-aware adverse-condition scoring, the conditions aggregator combines source fetches into a condition snapshot

CONTRACTS CHANGE WITH THE CODE · SOURCE LINKS ARE PROVIDED SO THE CURRENT RULES CAN BE CHECKED DIRECTLY