vortexa-claude-skills 1.0.0

package/context/guardrails.md

@@ -0,0 +1,161 @@
+# Vortexa API Guardrails
+
+> These rules prevent the most common and costly mistakes when querying Vortexa's API.
+> Loaded automatically for every /vortexa: skill.
+
+---
+
+## Activity Filters (Most Common Errors)
+
+The #1 source of incorrect results is choosing the wrong `filter_activity`.
+
+| User Intent | CORRECT filter | WRONG Choice | Why Wrong |
+|---|---|---|---|
+| "exports", "shipped out", "departures" | `loading_end` | `loading_state` | `loading_state` = currently loading at berth, not departed. Volumes will be far too low. |
+| "imports", "arrivals", "received" | `unloading_start` | `unloading_state` | `unloading_state` = currently discharging, not arrived. Misses completed discharges. |
+| "loadings", "loading at port" | `loading_state` | `loading_end` | `loading_end` = already departed, not actively loading. |
+| "on the water", "afloat", "in transit" | `cargo_on_water_state` | `oil_on_water_state` | `oil_on_water_state` is DEPRECATED. Always use `cargo_on_water_state`. |
+| "floating storage" | `storing_state` | `cargo_on_water_state` | `cargo_on_water_state` includes all transit, not just storage. |
+| "everything", "all activity" | `any_activity` | omitting the parameter | Omitting defaults to `any_activity` but should always be explicit. |
+
+**NEVER** use `loading_state` when the user says "exports" -- this is the single most common mistake.
+
+**NEVER** use `oil_on_water_state` -- it is deprecated. Always use `cargo_on_water_state`.
+
+**ALWAYS** pair exports/imports with `intra_movements="exclude_intra_country"` to exclude domestic flows.
+
+**ALWAYS** set `filter_activity` explicitly -- never rely on the default.
+
+### Activity + Geography Logic
+
+| Query Pattern | filter_activity | Geography Filter | intra_movements |
+|---|---|---|---|
+| "Saudi exports" | `loading_end` | `filter_origins=[saudi_id]` | `exclude_intra_country` |
+| "China imports" | `unloading_start` | `filter_destinations=[china_id]` | `exclude_intra_country` |
+| "Saudi exports to China" | `loading_end` | `filter_origins=[saudi_id]` + `filter_destinations=[china_id]` | `exclude_intra_country` |
+| "crude on the water" | `cargo_on_water_state` | (none or storage_locations) | `all` |
+| "floating storage in MEG" | `storing_state` | `filter_storage_locations=[meg_id]` | `all` |
+
+---
+
+## Entity Resolution
+
+**NEVER** use entity names directly in API calls -- all filters require 64-character hex Vortexa IDs. Resolve names first using reference endpoints.
+
+**ALWAYS** specify `filter_layer` when searching geographies. Without it, "China" returns ports, regions, and the country -- the wrong ID will silently produce wrong results.
+
+**ALWAYS** handle multiple search matches with disambiguation -- present top matches to the user and ask them to confirm. NEVER guess which match is correct.
+
+**ALWAYS** use full 64-character hex IDs for API calls. Truncated 16-character IDs appear in `cargo_movement_id` joins but are not valid for filter parameters.
+
+| Common Mistake | Why It Fails | Correct Approach |
+|---|---|---|
+| `filter_origins=["Saudi Arabia"]` | Names are not valid filter values | Resolve via `Geographies().search(term="Saudi Arabia", filter_layer="country")` |
+| `Geographies().search(term="China")` without layer | Returns ports, regions, country -- wrong ID likely picked | Add `filter_layer="country"` |
+| Using 16-char ID from CM join | Filter APIs require full 64-char IDs | Use `.id` field from reference search results |
+| `Products().search(term="crude")` without checking layer | Returns group, group_product, category, grade matches | Verify `layer` column matches intent (usually `group`) |
+
+---
+
+## Date Ranges
+
+**NEVER** leave end dates at midnight (00:00:00) -- data from the last day will be excluded entirely. This is a silent data loss bug.
+
+**ALWAYS** use `datetime(year, month, day, 23, 59, 59)` for historical end dates.
+
+**ALWAYS** use calendar convention for named periods:
+- "last year" = full previous calendar year (Jan 1 to Dec 31)
+- "last month" = full previous calendar month
+- "last quarter" = full previous calendar quarter
+
+**ALWAYS** use trailing convention for number+period:
+- "last 6 months" = today minus 6 months to now (rolling)
+- "last 30 days" = today minus 30 days to now (rolling)
+
+See `date-units.md` for the complete date parsing and unit selection reference.
+
+---
+
+## API Defaults That Bite
+
+These defaults produce silently wrong results if not overridden.
+
+| Parameter | Default | Problem | Fix |
+|---|---|---|---|
+| `size` (search endpoints) | `1` | Returns only 1 record -- looks like data exists but is incomplete | Always set `size=500` for batch retrieval |
+| `filter_activity` | `any_activity` | Matches ALL cargo states, giving misleading aggregates | Always specify explicitly |
+| `timeseries_unit` | `b` (barrels) | Wrong for LNG (should be `t`) and rate queries (should be `bpd`) | Match unit to commodity: oil=`bpd`, LNG=`t`, LPG=`t` |
+| `intra_movements` | `all` | Includes domestic flows in export/import queries, inflating volumes | Set `exclude_intra_country` for international trade |
+| `quantity_at_time_of` | `load` | For LNG, loaded volume differs from discharged due to boil-off | Use `unload` when analyzing delivered volumes |
+| `filter_confidence` | `low` | Includes all confidence levels including uncertain data | Usually fine; set higher for high-confidence analysis |
+
+**NEVER** rely on `size=1` default for search endpoints. Always set to 500 or appropriate value.
+
+**ALWAYS** set both `timeseries_activity` AND `filter_activity` when they should differ (filter on one state, aggregate on another). They serve different purposes.
+
+---
+
+## Voyages-Specific
+
+**NEVER** mix V1 underscore naming with V2 hyphen naming:
+- V1: `origin_country`, `vessel_count`, `tonne_miles`
+- V2: `origin-country`, `voyage-count`, `tonne-miles-sum`
+- V2 metric and breakdown are constructor args; V1 they are search params
+
+**NEVER** forget the `exclude_overlapping_entries` behavior difference:
+- Timeseries: defaults to `true` (de-duplicates)
+- Search: defaults to `false` (may count overlapping days)
+
+**ALWAYS** check ballast voyage origin/destination inversion:
+- For ballast voyages, `origins` = last discharge port (not where the ballast voyage started)
+- For ballast voyages, `destinations` = next load port (not where the ballast voyage ends)
+- This is the opposite of laden voyage logic
+
+**ALWAYS** match `voyage_date_range_activity` to user intent:
+- "active vessels" = `active` (broadest, any overlap with time window)
+- "arrivals" = `arrivals` (voyage ended in window)
+- "departures" = `departures` (voyage started in window)
+
+---
+
+## Confirmation Step (Mandatory)
+
+**NEVER** execute an API call without showing filter confirmation to the user first.
+
+Before any data query, present:
+
+```
+Query: [restate the user's question]
+Endpoint: [CargoTimeSeries / CargoMovements / VoyagesSearchEnriched / etc.]
+Activity: [filter_activity value] ([user's term])
+Origin: [name (layer)] or "not specified"
+Destination: [name (layer)] or "not specified"
+Product: [name (layer)] or "not specified"
+Time: [start datetime] -> [end datetime]
+Unit: [unit (reason for default or user-specified)]
+Frequency: [value or "Please specify: daily/weekly/monthly?"]
+Intra: [exclude_intra_country for exports/imports, all otherwise]
+Additional: [any other filters applied]
+
+Confirm or adjust?
+```
+
+**ALWAYS** include the unit and its rationale in the confirmation.
+
+**ALWAYS** include the frequency. If not specified and not determinable from context, ask the user.
+
+**ALWAYS** wait for user confirmation or adjustment before executing.
+
+---
+
+## Quick Decision Table
+
+| If the user says... | Use endpoint | Key filter | Common trap |
+|---|---|---|---|
+| "how much crude exported" | CargoTimeSeries | `loading_end` | Using `loading_state` instead |
+| "list cargoes from X" | CargoMovements search | varies | Forgetting to set `size=500` |
+| "show voyages to Y" | VoyagesSearchEnriched | `destinations` | Forgetting to set `size=500` |
+| "monthly vessel count" | VoyagesTimeseries | `vessel_count` | Using V2 syntax with V1 |
+| "tonne-miles by class" | VoyagesTimeseriesV2 | `tonne-miles-sum` | Using V1 underscore names |
+| "port congestion" | Congestion breakdown | `breakdown_property` | Using VoyagesTimeseries instead |
+| "floating storage levels" | CargoTimeSeries | `storing_state` | Using `cargo_on_water_state` |