vortexa-claude-skills 1.0.0

package/commands/vortexa/compare.md

@@ -0,0 +1,315 @@
+---
+name: vortexa:compare
+description: "Compare cargo flows period-over-period or region-over-region with overlay charts and metrics"
+argument-hint: "compare crude exports from Saudi Arabia 2025 vs 2024, monthly"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Run comparison analytics on cargo flows -- either period-over-period (e.g., 2025 vs 2024) or region-over-region (e.g., Europe vs Asia imports). Produces overlay line charts with computed metrics (absolute change, percentage change, averages, totals). Uses CargoTimeSeries for data and `comparison_overlay_chart()` from lib/visualization.py.
+</objective>
+
+<execution_context>
+## Pre-loaded Context (via CLAUDE.md @imports)
+The following are automatically available -- do NOT re-read them:
+- context/guardrails.md -- NEVER/ALWAYS rules for all Vortexa API calls
+- context/entity-resolution.md -- How to resolve entity names to hex IDs
+- context/date-units.md -- Date parsing rules and unit defaults
+
+## Required Context (Read on demand)
+Read before processing the user's query:
+- context/cargo-movements.md -- Full CTS parameters, activity filters, timeseries_property values
+</execution_context>
+
+## Setup Check
+@commands/vortexa/_check-setup.md
+
+<process>
+
+## Step 1: Read Endpoint Context
+
+Read `context/cargo-movements.md` for CTS parameters, activity filter rules, and frequency options.
+
+## Step 2: Parse the Query and Determine Mode
+
+Analyze $ARGUMENTS using signal word routing to determine the comparison mode:
+
+### Signal Word Routing
+
+**Period mode** -- year or time-based comparison:
+- Year references: 2025, 2024, "last year", "this year", "vs 2023"
+- Explicit period phrases: "year over year", "YoY", "month over month", "MoM", "QoQ", "quarter over quarter"
+- Multiple date ranges: "Q1 2025 vs Q1 2024", "Jan-Jun 2025 vs Jan-Jun 2024"
+
+**Region mode** -- geographic comparison:
+- Geographic references used as comparison items: "Europe vs Asia", "Middle East vs West Africa"
+- Multiple origins or destinations being compared: "Saudi vs Iraq exports", "China vs India imports"
+
+**Both present** -- ambiguous, ask:
+"I see both year and region references. Are you comparing time periods or geographies?"
+
+**Neither clear** -- ask:
+"What would you like to compare? Time periods (e.g., 2025 vs 2024) or regions (e.g., Europe vs Asia)?"
+
+### Extract Parameters
+
+- **Comparison items**: 2-5 items. If more than 5: "That's a lot of comparisons. Try /vortexa:breakdown for dimension analysis instead."
+- **Product**: commodity (crude, LNG, etc.)
+- **Activity**: same rules as cargo-flows (exports=loading_end, imports=unloading_start, etc.)
+- **Base query parameters**: origin, destination, time range, unit, frequency
+
+**For period mode:**
+- Each comparison item is a time period (year, quarter, month range)
+- Normalize x-axis to common reference: month names (Jan, Feb, ...) for year comparisons, week numbers for quarter comparisons
+- Default frequency: monthly for year comparisons, weekly for quarter comparisons, daily for month comparisons
+
+**For region mode:**
+- Each comparison item is a geography (country, region, shipping region)
+- Use the same time range for all items
+- x-axis is the shared date range (no normalization needed)
+
+## Step 3: Check for Missing Parameters
+
+Ask targeted questions BEFORE the confirmation step. Never default silently.
+
+**Required (ask if missing):**
+- **Comparison items** -- MUST have at least 2 items. Ask: "What periods/regions are you comparing?"
+- **Product** -- MUST be specified. Ask if missing.
+- **Activity** -- MUST be specified. If direction ambiguous, ask: "exports from origin or imports to destination?"
+
+**Mode-specific required:**
+- **Period mode**: frequency (default monthly for year comparisons, but confirm)
+- **Region mode**: time range (MUST be specified)
+
+**Ask if not specified:**
+- **Unit** -- Apply commodity defaults (oil=bpd, LNG=t, LPG=t). Ask if ambiguous.
+- **Geography filters** -- optional but commonly specified (e.g., "from Saudi Arabia" applies to all periods)
+
+Ask one parameter at a time. Do NOT ask all missing params in a bulk dump.
+
+## Step 4: Resolve Entity IDs
+
+For each entity mentioned (product, geography filters, region comparison items):
+1. Check `lib/aliases.json` for common shorthands (ME, AG, USG, ARA, etc.)
+2. Call `lib/entities.py` resolve functions with the correct entity type and layer:
+   - `resolve_geography(term, layer)` for origins/destinations and region comparison items
+   - `resolve_product(term, layer)` for products
+   - `resolve(term, entity_type, layer, cache)` for the unified resolver with caching
+3. If multiple matches: present top 3 candidates. Ask user to pick. NEVER auto-correct.
+4. If zero matches: tell user the term wasn't found, suggest checking spelling or trying a broader term.
+
+Use `EntityCache()` from `lib/entities.py` for the session to avoid re-resolving the same entities.
+
+## Step 5: Confirm Before Executing (MANDATORY)
+
+**Period mode confirmation:**
+```
+Query: [restate]
+Analysis: Period comparison
+Endpoint: CargoTimeSeries
+Comparing: [period1] vs [period2] (vs ...)
+Activity: [filter_activity] ([user's term])
+Origin: [name (layer)] or "not specified"
+Destination: [name (layer)] or "not specified"
+Product: [name (layer)]
+Unit: [unit] ([reason])
+Frequency: [value]
+Chart: Overlay lines + difference table
+
+Confirm or adjust?
+```
+
+**Region mode confirmation:**
+```
+Query: [restate]
+Analysis: Region comparison
+Endpoint: CargoTimeSeries
+Comparing: [region1] vs [region2] (vs ...)
+Activity: [filter_activity] ([user's term])
+Product: [name (layer)]
+Time: [start] -> [end]
+Unit: [unit] ([reason])
+Frequency: [value]
+Chart: Overlay lines + metrics table
+
+Confirm or adjust?
+```
+
+NEVER execute without confirmation. Wait for user response.
+
+## Step 6: Generate & Execute Code Artifact
+
+### Period Mode Code
+
+Generate code that:
+1. Runs a separate CTS query per period using `CargoTimeSeries` directly (no split needed)
+2. Normalizes x-axis: for year comparisons, map dates to month labels (Jan, Feb, ...) so lines overlay correctly
+3. Builds `series_dict` mapping period names to value lists
+4. Computes metrics inline (see metrics section below)
+5. Calls `comparison_overlay_chart(series_dict, x_labels, title, y_label)`
+6. Prints metrics table and saves chart
+
+### Region Mode Code
+
+Generate code that:
+1. Runs a separate CTS query per region (filtering by the region geography) with same time range
+2. x-axis is the shared date range (no normalization needed)
+3. Builds `series_dict` mapping region names to value lists
+4. Same metrics computation and chart generation
+
+### Metrics Computation
+
+Compute comparison metrics inline in generated code (NOT a lib/ function -- keep it clean with a small inline helper):
+
+```python
+# Compute comparison metrics
+metrics = {}
+for name, values in series_dict.items():
+    metrics[name] = {
+        "Total": sum(v for v in values if v),
+        "Average": sum(v for v in values if v) / len([v for v in values if v]) if any(values) else 0,
+    }
+# Difference table (pairwise from first comparison item)
+base = list(series_dict.keys())[0]
+for name in list(series_dict.keys())[1:]:
+    diff = metrics[name]["Total"] - metrics[base]["Total"]
+    pct = (diff / metrics[base]["Total"] * 100) if metrics[base]["Total"] else 0
+    print(f"{name} vs {base}: {diff:+,.0f} ({pct:+.1f}%)")
+```
+
+### Code Artifact Template
+
+```python
+"""Vortexa Compare: {description}
+Generated by /vortexa:compare
+Date: {date}
+"""
+from datetime import datetime
+import os
+import sys; sys.path.insert(0, "lib")
+from entities import resolve_geography, resolve_product, EntityCache
+from visualization import comparison_overlay_chart
+
+cache = EntityCache()
+{entity_resolution}
+
+# Query each comparison item
+from vortexasdk import CargoTimeSeries
+series_dict = {}
+{per_item_queries}
+
+# X-axis labels
+x_labels = {x_labels}
+
+# Metrics
+{metrics_computation}
+
+# Chart
+fig = comparison_overlay_chart(series_dict, x_labels=x_labels, title="{title}", y_label="{unit_label}")
+
+os.makedirs("output", exist_ok=True)
+filepath = f"output/{slug}_compare_{datetime.now().strftime('%Y-%m-%d')}.html"
+fig.write_html(filepath, auto_open=True)
+print(f"Chart saved: {filepath}")
+```
+
+**Period mode per-item query pattern:**
+```python
+# Example: 2025 vs 2024
+for year in [2025, 2024]:
+    df = CargoTimeSeries().search(
+        filter_activity=...,
+        filter_time_min=datetime(year, 1, 1),
+        filter_time_max=datetime(year, 12, 31, 23, 59, 59),
+        filter_products=[product_id],
+        filter_origins=[...],  # if specified
+        filter_destinations=[...],  # if specified
+        timeseries_unit=...,
+        timeseries_frequency=...,
+    ).to_df()
+    series_dict[str(year)] = df["value"].tolist()
+
+x_labels = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+            "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+```
+
+**Region mode per-item query pattern:**
+```python
+# Example: Europe vs Asia
+for region_name, region_id in [("Europe", europe_id), ("Asia", asia_id)]:
+    df = CargoTimeSeries().search(
+        filter_activity=...,
+        filter_time_min=...,
+        filter_time_max=...,
+        filter_products=[product_id],
+        filter_destinations=[region_id],  # or filter_origins depending on activity
+        timeseries_unit=...,
+        timeseries_frequency=...,
+    ).to_df()
+    series_dict[region_name] = df["value"].tolist()
+
+x_labels = df["key"].tolist()  # shared date buckets
+```
+
+After generating:
+- Ask user: "Save as new file, or add to an existing notebook/script?" Default: new file.
+- If new file: create `vortexa_compare_{slug}.py` in project directory.
+- Run the generated code to get results.
+
+## Step 7: Present Results
+
+- Show metrics summary table:
+  - Total and Average per comparison item
+  - Absolute change and percentage change (pairwise from first item)
+- Show overlay chart HTML path: "Chart saved: output/{slug}_compare_{date}.html"
+- Methodology footnote using confirmed parameters:
+  ```
+  Methodology: CargoTimeSeries (comparison) | {mode} | {items} | {activity} | {filters} | {frequency} | {unit}
+  ```
+  Example: `Methodology: CargoTimeSeries (comparison) | period | 2025 vs 2024 | loading_end | filter_origins=[Saudi Arabia] | monthly | bpd`
+- Offer: "Export to CSV?" and "Want a detailed summary?"
+
+## Step 8: Summary (if triggered)
+
+**Smart trigger:** If the user's query contains "analyze", "summarize", "explain results", "what does this show", or "key findings" -- generate the summary automatically.
+
+**Post-query offer:** After showing results, always offer: "Want a detailed summary?"
+
+**Summary content** -- comparison-specific insights:
+- Which comparison item has the highest total volume
+- Growth/decline trends: percentage change between items
+- Notable crossover points: where one item overtakes another on the chart
+- Seasonal patterns: months where differences are largest/smallest
+- Peak and trough identification per item
+
+**Brief summary (default):** 3-5 bullet points with specific numbers.
+
+**Extended summary (if user requests "detailed summary" or "full analysis"):**
+- 100-200 word narrative in market commentary style
+- Covers all the above plus broader context
+
+After showing the summary, offer: "Save this summary to a .md file?"
+If yes: create `output/{description}_summary_{date}.md`
+
+## Error Handling
+
+Report immediately in plain English, no auto-retry:
+
+- **401 Unauthorized**: "API key is invalid or expired. Run /vortexa:init to check your setup."
+- **500 Server Error**: "Vortexa API returned a server error. Try again in a few minutes."
+- **Timeout**: "Query timed out. Try narrowing the date range or reducing filters."
+- **Empty results**: "No data found for this query. Check that the entity names, date range, and filters are correct."
+- **Entity not found**: "The term '{term}' returned no matches. Check spelling or try a broader term."
+- **Multiple entity matches**: "{n} matches found for '{term}': [list]. Which did you mean?"
+- **Too many items**: "More than 5 comparison items requested. Try /vortexa:breakdown for dimension analysis instead."
+- **Mismatched data lengths**: "The comparison periods returned different numbers of data points. Check that all periods have complete data coverage."
+
+Never auto-retry. Never self-correct. Report the error and let the user decide.
+
+</process>

package/commands/vortexa/custom.md

@@ -0,0 +1,214 @@
+---
+name: vortexa:custom
+description: "Run any Vortexa API query or improve existing Vortexa Python code"
+argument-hint: "Average waiting time at Fujairah for VLCCs"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Handle any Vortexa API query by loading all endpoint context docs and writing custom SDK code. Also read, validate, fix, or extend existing user Vortexa Python code. This is the open-ended skill for queries that don't fit the focused /vortexa:cargo-flows or /vortexa:voyages workflows.
+</objective>
+
+<execution_context>
+## Pre-loaded Context (via CLAUDE.md @imports)
+The following are automatically available -- do NOT re-read them:
+- context/guardrails.md -- NEVER/ALWAYS rules for all Vortexa API calls
+- context/entity-resolution.md -- How to resolve entity names to hex IDs
+- context/date-units.md -- Date parsing rules and unit defaults
+
+## Required Context (Read ALL on demand)
+Read all three endpoint context docs before processing -- the custom skill needs the full API surface:
+- context/cargo-movements.md -- CTS/CM parameters, activity filters, column names
+- context/voyages.md -- VSE/VTS parameters, voyage definitions, V1/V2 differences
+- context/reference-endpoints.md -- Entity lookups, product hierarchy, geography layers
+</execution_context>
+
+## Setup Check
+@commands/vortexa/_check-setup.md
+
+<process>
+
+## Step 1: Read ALL Endpoint Context
+
+Read all three endpoint context docs:
+- `context/cargo-movements.md`
+- `context/voyages.md`
+- `context/reference-endpoints.md`
+
+The custom skill operates across the full API surface. All three docs are needed regardless of query type.
+
+## Step 2: Determine Intent
+
+Analyze $ARGUMENTS to classify the request:
+
+**A. New data query** -- user wants data the API can provide
+- Could involve any endpoint: CTS, CM, VSE, VTS, Congestion, Reference
+- Could combine multiple endpoints in a single query (e.g., CM + VSE for OOW enrichment)
+- Proceed to Steps 3-9 (standard query workflow)
+
+**B. Code improvement** -- user references existing code
+- User mentions a .py file, notebook, or pastes code
+- Read the referenced file(s) first
+- Use context docs to validate, fix, or extend the code
+- Check for common mistakes against guardrails.md rules (wrong activity filter, missing entity resolution, midnight end dates, deprecated oil_on_water_state, etc.)
+- Explain what was wrong and why the fix is correct, citing specific guardrails rules
+- Skip the confirmation step (user already has code)
+
+**C. Redirect** -- query fits a focused skill better
+- Straightforward CTS/CM query: suggest "This looks like a cargo flow query -- try `/vortexa:cargo-flows {query}` for a more focused workflow."
+- Straightforward VSE/VTS query: suggest "This looks like a voyage query -- try `/vortexa:voyages {query}` for a more focused workflow."
+- Still process the query if the user insists or if the query combines multiple endpoints
+
+## Step 3: Parse the Query (New Data Queries)
+
+Extract all relevant parameters from the natural language query:
+- **Endpoint(s)**: Which API endpoint(s) are needed? May be multiple.
+- **Product**: What commodity?
+- **Geography**: Origins, destinations, storage locations -- what layers?
+- **Activity**: What movement stage? (exports=loading_end, imports=unloading_start, etc.)
+- **Vessel filters**: Class, flag, DWT, IMO, age, scrubber status
+- **Corporate filters**: Owner, charterer, time charterer
+- **Time range**: Apply date-units.md calendar/trailing convention
+- **Unit**: Apply commodity defaults (oil=bpd, LNG=t, LPG=t)
+- **Frequency**: For timeseries queries
+- **Additional**: Intra movements, confidence, STS, waypoints, congestion breakdowns
+
+## Step 4: Check for Missing Parameters
+
+Same conservative policy as cargo-flows and voyages: always ask, never default silently.
+Ask one parameter at a time. Do NOT bulk-dump all missing params.
+
+Required for every query:
+- Time range -- MUST be specified
+- At least one meaningful filter (product, geography, vessel, or corporate)
+
+For timeseries: frequency must be specified or asked.
+For search endpoints: set `size=500`.
+
+## Step 5: Resolve Entity IDs
+
+Same entity resolution workflow as the other skills:
+1. Check `lib/aliases.json` for common shorthands (ME, AG, USG, ARA, etc.)
+2. Call `lib/entities.py` resolve functions: `resolve_geography(term, layer)`, `resolve_product(term, layer)`, `resolve(term, entity_type, layer, cache)`
+3. Multiple matches: present top 3 candidates, ask user to pick. NEVER auto-correct.
+4. Zero matches: tell the user, suggest alternatives.
+5. Use `EntityCache()` for the session to avoid re-resolving.
+
+## Step 6: Confirm Before Executing (MANDATORY for new queries)
+
+Present the parsed query adapted to the specific endpoint(s):
+
+```
+Query: [restate the user's question]
+Endpoint(s): [list all endpoints being used]
+[endpoint-specific parameters -- activity, voyage status, metric, breakdown, etc.]
+Origin: [name (layer)] or "not specified"
+Destination: [name (layer)] or "not specified"
+Product: [name (layer)] or "not specified"
+Time: [start datetime] -> [end datetime] ([interpretation])
+Unit: [unit] ([reason])
+Frequency: [value] (timeseries only)
+Additional: [any other filters]
+
+Confirm or adjust?
+```
+
+NEVER execute without confirmation. Wait for user response.
+Skip this step ONLY for code improvement (intent B) where the user already has code.
+
+## Step 7: Generate & Execute Code Artifact
+
+Code is ALWAYS custom SDK code (Mode 2) -- reference the relevant context doc for correct parameter names and syntax.
+
+```python
+"""Vortexa Query: {description}
+Generated by /vortexa:custom
+Date: {date}
+"""
+from datetime import datetime
+import sys; sys.path.insert(0, "lib")
+from entities import resolve, EntityCache
+
+# Custom query -- built from Vortexa API documentation
+cache = EntityCache()
+# {entity resolution}
+# {SDK calls using vortexasdk}
+# {result formatting}
+```
+
+Key rules:
+- Write raw SDK calls using vortexasdk, referencing endpoint context docs for correct syntax
+- Can combine multiple endpoints (e.g., CM + VSE for OOW enrichment, Reference + CTS for entity lookup then query)
+- Use lib/ functions as building blocks where they fit (entity resolution, column rename, timeseries parsing)
+- Add comment: `# Custom query -- built from Vortexa API documentation`
+- Code must be self-contained and re-runnable
+
+For code improvement (intent B):
+- Read the user's existing file
+- Identify issues using context docs and guardrails.md
+- Fix or extend in-place, or create a corrected version
+- Explain each change with references to specific guardrails rules
+
+Ask user: "Save as new file, or add to existing script/notebook?" Default: new file.
+
+## Step 8: Present Results
+
+Terminal summary (same pattern as cargo-flows and voyages):
+- Brief natural language description of what was queried
+- Row count and date range covered
+- DataFrame preview with row cap (daily=30, weekly=52, monthly=24, yearly=all)
+- File path to generated code artifact
+- Offer: "Export to CSV?"
+
+For code improvement: show a diff summary of what changed and why.
+
+After the DataFrame preview and before the export offer, show a one-line methodology footnote using the CONFIRMED parameters from Step 6:
+```
+Methodology: {Endpoint(s)} | {activity} | {key filters} | {frequency} | {unit} | {other relevant params}
+```
+Example: `Methodology: CargoMovements.search | loading_end | filter_origins=[Saudi Arabia] | filter_products=[Crude & Condensates] | size=500`
+
+Use human-readable names for entity filters (not hex IDs). Skip for code improvement (intent B).
+
+## Step 9: Summary (if triggered)
+
+**Smart trigger:** If the user's query contains "analyze", "summarize", "explain results", "what does this show", or "key findings" -- generate the summary automatically.
+
+**Post-query offer:** After showing results, always offer: "Want a summary of these results?"
+
+**Brief summary (default):**
+Analyze the DataFrame and produce 3-5 bullet points:
+- Top 3-5 contributors by volume with percentages of total
+- Period-over-period change if comparable time periods exist
+- Notable outliers: spikes, drops, record values, trend reversals
+- Each bullet includes specific numbers, not vague descriptions
+
+**Extended summary (if user requests "detailed summary" or "full analysis"):**
+- 100-200 word narrative paragraph in market commentary style
+- Includes everything from brief plus trend descriptions and broader context
+
+After showing the summary, offer: "Save this summary to a .md file?"
+If yes: create `output/{description}_summary_{date}.md`
+
+Skip for code improvement (intent B) -- summaries are for query results, not code reviews.
+
+## Error Handling
+
+Same patterns as cargo-flows and voyages -- report immediately in plain English, no auto-retry:
+
+- **401 Unauthorized**: "API key is invalid or expired. Run /vortexa:init to check your setup."
+- **500 Server Error**: "Vortexa API returned a server error. Try again in a few minutes."
+- **Timeout**: "Query timed out. Try narrowing the date range or reducing filters."
+- **Empty results**: "No data found. Check entity names, date range, and filters."
+- **Entity not found**: "The term '{term}' returned no matches. Check spelling or try a broader term."
+- **Multiple entity matches**: Present top candidates with name, layer, and first 8 chars of ID. Ask user to pick.
+
+Never auto-retry. Never self-correct. Report the error and let the user decide.
+
+</process>

package/commands/vortexa/explain.md

@@ -0,0 +1,124 @@
+---
+name: vortexa:explain
+description: "Get plain-English explanations of Vortexa data model, filters, entity hierarchies, and methodology"
+argument-hint: "What is loading_end vs loading_state?"
+allowed-tools:
+  - Read
+---
+
+<objective>
+Answer any question about the Vortexa data model, API methodology, entity hierarchies, filter options, activity types, and endpoint behavior using ONLY the information in the context documentation. Support conversational follow-ups for guided exploration.
+
+This is a Knowledge Variant skill -- it generates no code, makes no API calls, and produces no DataFrames. It reads documentation and explains concepts.
+</objective>
+
+<execution_context>
+## Pre-loaded Context (via CLAUDE.md @imports)
+The following are automatically available -- do NOT re-read them:
+- context/guardrails.md -- Activity filters, entity resolution rules, date ranges, API defaults, voyages rules, confirmation step, quick decision table
+- context/entity-resolution.md -- Resolution workflow, SDK methods, geography/product/vessel/corporate hierarchies, disambiguation protocol
+- context/date-units.md -- Calendar vs trailing date parsing, frequency selection, unit defaults by commodity
+
+## Required Context (Read on demand)
+Read ALL three endpoint context docs at the start of the conversation:
+- context/cargo-movements.md -- CTS and CM parameters, activity filters, column names, breakdown/split properties, worked examples
+- context/voyages.md -- VSE and VTS parameters, voyage definitions, events, V1/V2 differences, freight metrics
+- context/reference-endpoints.md -- Entity hierarchies, SDK methods, product/geography/vessel/corporate layers, search patterns
+</execution_context>
+
+<process>
+
+## Step 1: Read All Context Documentation
+
+Read all three endpoint context docs:
+- `context/cargo-movements.md`
+- `context/voyages.md`
+- `context/reference-endpoints.md`
+
+Combined with the pre-loaded guardrails, entity-resolution, and date-units docs, this gives access to the full Vortexa knowledge base (~4,000 lines across 6 docs). This is a one-time read at the start of the conversation -- no need to re-read for follow-up questions.
+
+## Step 2: Identify the Topic
+
+Analyze $ARGUMENTS to determine what the user is asking about. Common topic categories:
+
+**Entity hierarchies** -- "What products are there?", "How are geographies organized?", "What vessel classes exist?"
+- Answer from: reference-endpoints.md (full hierarchy tables), entity-resolution.md (resolution workflow)
+
+**Filter behavior** -- "What is loading_end?", "Difference between loading_state and loading_end?", "When should I use exclude_intra_country?"
+- Answer from: guardrails.md (activity filter table, geography logic table), cargo-movements.md (parameter details)
+
+**Activity types** -- "What activities can I filter on?", "What does storing_state mean?", "What's cargo_on_water_state?"
+- Answer from: guardrails.md (activity table with correct/wrong choices), cargo-movements.md (activity definitions)
+
+**Methodology** -- "How does CTS differ from CM?", "What's the CM-Authoritative OOW pattern?", "How does quantity_at_time_of work?"
+- Answer from: cargo-movements.md (endpoint comparison, OOW pattern), voyages.md (methodology sections)
+
+**API mechanics** -- "V1 vs V2 voyages timeseries?", "What units are available?", "How do date ranges work?"
+- Answer from: voyages.md (V1/V2 differences), date-units.md (units table), guardrails.md (API defaults)
+
+**Endpoint guidance** -- "When should I use Voyages vs CargoMovements?", "What is VoyagesSearchEnriched?", "What breakdown properties does CTS support?"
+- Answer from: voyages.md (endpoint selection), cargo-movements.md (split properties), guardrails.md (quick decision table)
+
+## Step 3: Search Context Docs and Synthesize Answer
+
+Find the relevant information across the loaded context docs and synthesize a plain-English explanation.
+
+### Accuracy Constraint
+
+**ONLY use information from the context docs.** Do NOT supplement with training knowledge or assumptions about the Vortexa API. If it is not written in the 6 context docs, do not state it as fact. This ensures the explanation matches exactly what the query skills (/vortexa:cargo-flows, /vortexa:voyages, /vortexa:breakdown, /vortexa:custom) actually use.
+
+### Synthesis Rules
+
+1. **If the topic IS covered:** Explain it clearly using the doc content. Include specific rules, tables, and examples from the docs. Cite which doc the information comes from (e.g., "Per guardrails.md, loading_end is the correct activity for exports").
+
+2. **If the topic is NOT covered:** Say "This concept isn't documented in the current context. The context docs cover: entity hierarchies, activity filters, date conventions, cargo movements (CTS/CM), voyages (VSE/VTS), and reference endpoints (products, geographies, vessels, corporations)."
+
+3. **If the topic spans multiple docs:** Cross-reference them. For example, "How do I query crude exports?" touches guardrails.md (activity=loading_end), entity-resolution.md (resolve product ID), cargo-movements.md (CTS parameters), and date-units.md (time range format).
+
+### Formatting Guidelines
+
+- Structure answers with clear headers or bullet points for readability
+- For hierarchy questions, show the hierarchy visually:
+  ```
+  group > group_product > category > grade
+  ```
+- For "which should I use" questions, reference the decision tables in guardrails.md and the endpoint context docs
+- For filter comparison questions, use side-by-side tables showing the differences
+- For "what options are there" questions, list all options with brief descriptions from the docs
+- For common-mistake questions, highlight the NEVER/ALWAYS rules from guardrails.md
+- Keep explanations concise -- the user can always ask follow-ups for more detail
+
+## Step 4: Offer Drill-Down
+
+After answering, offer follow-up exploration with 2-3 specific related topics the user might want to explore next:
+
+"Want to explore deeper into any of these? For example:
+- [related topic 1 based on what was just explained]
+- [related topic 2 that naturally follows]
+- [related topic 3 for broader context]"
+
+### Drill-Down Topic Selection
+
+Choose follow-up suggestions that naturally extend the current explanation:
+- If explaining an entity hierarchy -> suggest exploring a specific branch, or how to resolve IDs
+- If explaining a filter -> suggest comparing it with a commonly confused alternative
+- If explaining methodology -> suggest the related endpoint parameters or worked examples
+- If explaining an endpoint -> suggest when to use it vs alternatives, or its key parameters
+
+### Example Drill-Down Flows
+
+- "What products are there?" -> hierarchy shown -> "Tell me about Clean Products" -> sub-groups listed -> "What's the difference between category and grade?" -> explanation with examples
+- "What activities are there?" -> list with descriptions -> "What's the difference between cargo_on_water_state and storing_state?" -> detailed comparison with use cases
+- "How does entity resolution work?" -> workflow explained -> "Show me the geography layers" -> hierarchy with examples from each layer
+- "When should I use CTS vs CM?" -> decision criteria -> "How does the CM-Authoritative OOW pattern work?" -> step-by-step explanation
+- "What units are available?" -> full unit table -> "What's the default for LNG?" -> commodity defaults explained -> "How do rate units differ from absolute?" -> bpd vs b comparison
+
+### Conversational Continuity
+
+The skill is conversational -- it can answer multiple follow-up questions in the same session using the context docs already loaded in Step 1. Unlike the data query skills which are one-shot (parse, confirm, execute, present), this skill maintains a dialogue where each answer builds on previous context.
+
+If a follow-up question shifts to a topic better served by a data query, suggest the appropriate skill:
+- "Can you pull that data?" -> "Try `/vortexa:cargo-flows` or `/vortexa:voyages` for actual data queries"
+- "Show me a breakdown by origin" -> "Try `/vortexa:breakdown crude exports by origin`"
+
+</process>