--- title: "Volatility Heatmap" description: "Identify where rankings are unstable and likely to swing." order: 11 featured: false --- # 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 ```yaml 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: ```text 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. ```