Top 20 Over Time

What it does

Track and analyze brand rankings over time, grouping result snapshots by period (day or week) to identify entrants, exits, retained counts, average rank changes, and biggest movers within the top 20 ranks.

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. top-20-over-time.json).
  • A premium, beautifully styled markdown report must be saved to [skill_name].md (e.g. top-20-over-time.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. Period Grouping: Parse the updatedAt timestamp and group snapshots by period (either daily or weekly, depending on dataset density).
2. Filtering: Exclude any brand rankings where the position is greater than 20 (position <= 20).
3. Cohort Transition Metrics:
   • Entrants: Brands appearing in the top 20 in the current period that were not in the top 20 in the previous period.
   • Exits: Brands in the top 20 in the previous period that are no longer in the top 20 in the current period.
   • Retained Count: Brands that remained in the top 20 from the previous period to the current period.
   • Average Rank Change: For retained brands, calculate the average difference in ranks between the two periods (current rank minus previous rank).

Expected Output

The skill must generate two outputs in the local workspace:

1. top-20-over-time.json: Contains the raw structured analytical output, including the execution contract metadata, top20_by_period[], entrants and exits per period, retention rate percentage, biggest movers, confidence metrics, and the evidence map.

2. top-20-over-time.md: A premium, beautiful human-readable report. This report must contain:

   • Leaderboard Trends / top20_by_period[]: Formatted tables or lists showing top 20 rankings grouped by period.
   • Entrants & Exits: List of entrants[] and exits[] per period.
   • Retention Rate: The retention_rate_percent across periods.
   • Biggest Movers: List of biggest_movers[] showing the brands with the most significant position increases/decreases.
   • 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

• Period Sparsity: If the periods in the dataset are sparse or contain large gaps, flag low confidence and document this under confidence/limitations.
• No Unlabeled Interpolation: Do not interpolate missing data points or assume linear trends without explicitly labeling them as interpolated or estimated.
• No Web Lookups: Do not perform external web lookups or enrichment of brand data.
• No Hallucination: Do not invent brands, timestamps, rankings, or hidden fields 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: Top 20 Over Time
Goal: Track who appears in top 20 by period and how positions change.

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. `top-20-over-time.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `top-20-over-time.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. **Period Grouping**: Parse the `updatedAt` timestamp and group snapshots by period (either daily or weekly, depending on dataset density).
2. **Filtering**: Exclude any brand rankings where the `position` is greater than 20 (`position <= 20`).
3. **Cohort Transition Metrics**:
   - **Entrants**: Brands appearing in the top 20 in the current period that were not in the top 20 in the previous period.
   - **Exits**: Brands in the top 20 in the previous period that are no longer in the top 20 in the current period.
   - **Retained Count**: Brands that remained in the top 20 from the previous period to the current period.
   - **Average Rank Change**: For retained brands, calculate the average difference in ranks between the two periods (current rank minus previous rank).

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

1. **`top-20-over-time.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, `top20_by_period[]`, entrants and exits per period, retention rate percentage, biggest movers, confidence metrics, and the evidence map.

2. **`top-20-over-time.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Leaderboard Trends / top20_by_period[]**: Formatted tables or lists showing top 20 rankings grouped by period.
   - **Entrants & Exits**: List of `entrants[]` and `exits[]` per period.
   - **Retention Rate**: The `retention_rate_percent` across periods.
   - **Biggest Movers**: List of `biggest_movers[]` showing the brands with the most significant position increases/decreases.
   - **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:
- **Period Sparsity**: If the periods in the dataset are sparse or contain large gaps, flag low confidence and document this under confidence/limitations.
- **No Unlabeled Interpolation**: Do not interpolate missing data points or assume linear trends without explicitly labeling them as interpolated or estimated.
- **No Web Lookups**: Do not perform external web lookups or enrichment of brand data.
- **No Hallucination**: Do not invent brands, timestamps, rankings, or hidden fields that are not present in the ingested dataset.