Volatility Heatmap

What it does

Build a comprehensive brand-keyword rank time-series volatility heatmap matrix to identify unstable areas where rankings are highly unstable and likely to experience significant swings.

Execution Contract

Every execution of this skill must operate under the following contract:
- **ingestion_plan**: A documented plan for pulling data.
- **max_api_calls**: 3 (default, strictly enforced).
- **cache_key**: A unique key identifying the cached API dataset.
- **dataset_timestamp**: ISO timestamp of the ingested dataset.
- **analysis_mode**: `offline_only`

Data Access Policy

• API Target: Consume data from the FullMention API at GET /v2/runs/{runId}.
• Controlled Ingestion: Perform exactly one controlled ingestion pull from the FullMention API. Paginated batch fetching is preferred.
• API Decoupling: Do NOT treat the FullMention API as a persistent database or state-store; it is a read-only snapshot provider.
• 24-Hour TTL: FullMention v2 deletes run data after 24 hours, meaning offline persistence/database caching is a strict requirement for historical tracking.
• Local Persistence: Save all analytical outputs locally in the current workspace directory.
  • Raw structured JSON must be saved to [skill_name].json (e.g. volatility-heatmap.json).
  • A premium, beautifully styled markdown report must be saved to [skill_name].md (e.g. volatility-heatmap.md).
• Caching: Reuse the same stored dataset across iterative prompts. Do not repeat identical API calls.
• Refresh Window: Make additional API calls only if the user explicitly requests a refresh window or a missing page fetch.
• Rate Limits & Backoff: Respect API rate limits and backoff policies. Never run open-ended call loops.
• Allowed Sources:
  • Local working dataset produced from one ingestion pull of FullMention API data.
  • Optional user-provided local file/DB snapshot (read-only).
  • No repeated API fetching during analysis.

Required Input Fields & Parameters

The input dataset from the API/file must map to these fields:

• updatedAt (string, ISO-8601 timestamp of snapshot update)
• keyword (string, searched keyword)
• brandRankings[].name (string, brand name)
• brandRankings[].position (integer, brand rank position)

Analytical Method

Follow these step-by-step logic rules during analysis:

1. Rank Time-Series Construction: For each unique brand + keyword pair, compile all rank positions ordered chronologically by updatedAt.
2. Metrics Computation: For each cell (keyword x brand) in the matrix, calculate:
   • stdDevRank: Standard deviation of ranks across the time-series.
   • meanAbsoluteChange: Average absolute change between consecutive ranks.
   • disappearanceRate: Ratio of periods absent from the rankings after the first appearance.
3. Volatility Score Calculation: Combine these three metrics into a normalized volatility score from 0 to 100.
4. Heatmap Matrix Generation: Format a two-dimensional grid representing volatility_heatmap[keyword][brand] populated with the calculated Volatility Scores.
5. Stability Classification: Identify and highlight the top most unstable brand-keyword pairs and compile an overall market stability summary.

Expected Output

The skill must generate two outputs in the local workspace:

1. volatility-heatmap.json: Contains the raw structured analytical output, including the execution contract metadata, volatility_heatmap[keyword][brand] matrix data, top_unstable_pairs[] list, the stability_summary, confidence metrics, and the evidence map.

2. volatility-heatmap.md: A premium, beautiful human-readable report. This report must contain:

   • Volatility Heatmap Matrix: A visual markdown grid table displaying volatility_heatmap[keyword][brand] scores. Use color highlights or clear visual indicators (e.g. [🔴 High (85)], [🟡 Mid (40)], [🟢 Low (10)]) to represent volatility.
   • Top Unstable Pairs: Detailed list of brand-keyword combinations showing the highest volatility.
   • Stability Summary: Strategic overview of market dynamics and rank swing likelihoods.
   • Confidence & Limitations:
     • A confidence score from 0-100.
     • Confidence Rationale: Explanation of how the confidence score was derived.
     • Limitations: A list of data limitations or gaps.
   • Evidence Map: An array of objects evidence_map[] with:
     • finding_id
     • metric_name
     • source_field_paths[]
     • sample_result_ids[]

Guardrails & Constraints

• Minimum Time Points Constraint: High-quality volatility analysis requires a minimum of 3 chronological time points (snapshots). If the dataset has fewer than 3 time points, emit a prominent warning regarding insufficient historical depth.
• Flag Missing Data Bias: Explicitly declare and flag any potential missing-data biases or gaps in the time-series that could skew standard deviation or disappearance rates.
• No Web Lookups: Do not perform external web lookups or enrichment of brand data.
• No Hallucination: Do not invent brands, rankings, keywords, or timestamps that are not present in the ingested dataset.

Copy-ready Skill Prompt

Use this as a full copy/paste prompt in your AI tool:

Skill: Volatility Heatmap
Goal: Identify where rankings are unstable and likely to swing.

Data Access Policy:
- **API Target**: Consume data from the FullMention API at `GET /v2/runs/{runId}`.
- **Controlled Ingestion**: Perform exactly one controlled ingestion pull from the FullMention API. Paginated batch fetching is preferred.
- **API Decoupling**: Do NOT treat the FullMention API as a persistent database or state-store; it is a read-only snapshot provider.
- **24-Hour TTL**: FullMention v2 deletes run data after 24 hours, meaning offline persistence/database caching is a strict requirement for historical tracking.
- **Local Persistence**: Save all analytical outputs locally in the current workspace directory.
  - Raw structured JSON must be saved to `[skill_name].json` (e.g. `volatility-heatmap.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `volatility-heatmap.md`).
- **Caching**: Reuse the same stored dataset across iterative prompts. Do not repeat identical API calls.
- **Refresh Window**: Make additional API calls only if the user explicitly requests a refresh window or a missing page fetch.
- **Rate Limits & Backoff**: Respect API rate limits and backoff policies. Never run open-ended call loops.
- **Allowed Sources**:
  - Local working dataset produced from one ingestion pull of FullMention API data.
  - Optional user-provided local file/DB snapshot (read-only).
  - No repeated API fetching during analysis.

Input Fields & Params:
The input dataset from the API/file must map to these fields:
- `updatedAt` (string, ISO-8601 timestamp of snapshot update)
- `keyword` (string, searched keyword)
- `brandRankings[].name` (string, brand name)
- `brandRankings[].position` (integer, brand rank position)

Method:
Follow these step-by-step logic rules during analysis:
1. **Rank Time-Series Construction**: For each unique `brand` + `keyword` pair, compile all rank positions ordered chronologically by `updatedAt`.
2. **Metrics Computation**: For each cell (keyword x brand) in the matrix, calculate:
   - **`stdDevRank`**: Standard deviation of ranks across the time-series.
   - **`meanAbsoluteChange`**: Average absolute change between consecutive ranks.
   - **`disappearanceRate`**: Ratio of periods absent from the rankings after the first appearance.
3. **Volatility Score Calculation**: Combine these three metrics into a normalized `volatility score` from 0 to 100.
4. **Heatmap Matrix Generation**: Format a two-dimensional grid representing `volatility_heatmap[keyword][brand]` populated with the calculated Volatility Scores.
5. **Stability Classification**: Identify and highlight the top most unstable brand-keyword pairs and compile an overall market stability summary.

Expected Output:
The skill must generate two outputs in the local workspace:

1. **`volatility-heatmap.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, `volatility_heatmap[keyword][brand]` matrix data, `top_unstable_pairs[]` list, the `stability_summary`, confidence metrics, and the evidence map.

2. **`volatility-heatmap.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Volatility Heatmap Matrix**: A visual markdown grid table displaying `volatility_heatmap[keyword][brand]` scores. Use color highlights or clear visual indicators (e.g. `[🔴 High (85)]`, `[🟡 Mid (40)]`, `[🟢 Low (10)]`) to represent volatility.
   - **Top Unstable Pairs**: Detailed list of brand-keyword combinations showing the highest volatility.
   - **Stability Summary**: Strategic overview of market dynamics and rank swing likelihoods.
   - **Confidence & Limitations**:
     - A confidence score from 0-100.
     - **Confidence Rationale**: Explanation of how the confidence score was derived.
     - **Limitations**: A list of data limitations or gaps.
   - **Evidence Map**: An array of objects `evidence_map[]` with:
     - `finding_id`
     - `metric_name`
     - `source_field_paths[]`
     - `sample_result_ids[]`

Guardrails:
- **Minimum Time Points Constraint**: High-quality volatility analysis requires a minimum of 3 chronological time points (snapshots). If the dataset has fewer than 3 time points, emit a prominent warning regarding insufficient historical depth.
- **Flag Missing Data Bias**: Explicitly declare and flag any potential missing-data biases or gaps in the time-series that could skew standard deviation or disappearance rates.
- **No Web Lookups**: Do not perform external web lookups or enrichment of brand data.
- **No Hallucination**: Do not invent brands, rankings, keywords, or timestamps that are not present in the ingested dataset.