---
title: "Rank Volatility Monitor"
description: "Track rank instability across multiple snapshot pulls."
order: 10
featured: false
---

   
                                
                                                                     
         
   
# Rank Volatility Monitor

## What it does

Track and analyze brand rank instability and volatility over multiple snapshot periods, calculating standard deviations, disappearance rates, and mean absolute rank changes.

## 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. `rank-volatility-monitor.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `rank-volatility-monitor.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 Series Construction**: Build a chronological rank series for each unique `brand` + `keyword` combination across all snapshot periods sorted by `updatedAt`.
2. **Instability Metrics Calculation**:
   - **Standard Deviation of Rank (`stdDevRank`)**: Calculate the standard deviation of rankings across the series.
   - **Disappearance Rate (`disappearanceRate`)**: Calculate the frequency with which a brand disappears from the top rankings after having been present:
     $$\text{disappearanceRate} = \frac{\text{periods absent}}{\text{total periods after first appearance}}$$
   - **Mean Absolute Rank Change (`meanAbsoluteRankChange`)**: Calculate the average absolute difference between consecutive rank positions:
     $$\text{meanAbsoluteRankChange} = \frac{\sum | \text{rank}_t - \text{rank}_{t-1} |}{N-1}$$
3. **Volatility Scoring**: Combine these metrics to calculate a single normalized `volatility score` from 0 to 100 (where 100 represents maximum instability/volatility).

## Expected Output

The skill must generate two outputs in the local workspace:

1. **`rank-volatility-monitor.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, per-brand volatility calculations, anomaly alerts, confidence metrics, and the evidence map.

2. **`rank-volatility-monitor.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Volatility Leaderboard**: Summary table showing brand names, keywords, calculated standard deviation, disappearance rate, mean absolute rank change, and the final Volatility Score (0-100).
   - **Anomaly Alerts**: Clear warnings or callouts highlighting brand-keyword pairs exhibiting unusually high or sudden volatility shifts.
   - **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**: Stable calculation requires a minimum of 3 unique chronological time points (snapshots). If the dataset contains fewer than 3 time points, emit a prominent warning regarding insufficient historical depth and lower the confidence score accordingly.
- **No Silent Interpolation**: Do not silently interpolate missing periods or rank positions. Any gaps or assumed values must be explicitly declared and highlighted as a limitation.
- **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: Rank Volatility Monitor
Goal: Track rank instability across multiple snapshot pulls.

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. `rank-volatility-monitor.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `rank-volatility-monitor.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.

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 Series Construction**: Build a chronological rank series for each unique `brand` + `keyword` combination across all snapshot periods sorted by `updatedAt`.
2. **Instability Metrics Calculation**:
   - **Standard Deviation of Rank (`stdDevRank`)**: Calculate the standard deviation of rankings across the series.
   - **Disappearance Rate (`disappearanceRate`)**: Calculate the frequency with which a brand disappears from the top rankings after having been present:
     $$\text{disappearanceRate} = \frac{\text{periods absent}}{\text{total periods after first appearance}}$$
   - **Mean Absolute Rank Change (`meanAbsoluteRankChange`)**: Calculate the average absolute difference between consecutive rank positions:
     $$\text{meanAbsoluteRankChange} = \frac{\sum | \text{rank}_t - \text{rank}_{t-1} |}{N-1}$$
3. **Volatility Scoring**: Combine these metrics to calculate a single normalized `volatility score` from 0 to 100 (where 100 represents maximum instability/volatility).

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

1. **`rank-volatility-monitor.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, per-brand volatility calculations, anomaly alerts, confidence metrics, and the evidence map.

2. **`rank-volatility-monitor.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Volatility Leaderboard**: Summary table showing brand names, keywords, calculated standard deviation, disappearance rate, mean absolute rank change, and the final Volatility Score (0-100).
   - **Anomaly Alerts**: Clear warnings or callouts highlighting brand-keyword pairs exhibiting unusually high or sudden volatility shifts.
   - **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**: Stable calculation requires a minimum of 3 unique chronological time points (snapshots). If the dataset contains fewer than 3 time points, emit a prominent warning regarding insufficient historical depth and lower the confidence score accordingly.
- **No Silent Interpolation**: Do not silently interpolate missing periods or rank positions. Any gaps or assumed values must be explicitly declared and highlighted as a limitation.
- **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.
```