---
title: "Citation Momentum"
description: "Track citation share and growth by domain across periods."
order: 9
featured: false
---

   
                          
                                                                        
        
   
# Citation Momentum

## What it does

Track and analyze domain citation shares, period-over-period growth rates, and overall citation concentration trends chronologically across multiple snapshot periods.

## 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. `citation-momentum.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `citation-momentum.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)
- `websiteRankings[].domain` (string, domain name)
- `websiteRankings[].position` (integer, domain rank position)
- `fanout.sources[].domain` (string, fanout source domain)
- `truncated.fanoutSourcesPreview` (boolean, indicates if fanout sources are truncated inline)

## Analytical Method

Follow these step-by-step logic rules during analysis:
1. **Domain Mentions Grouping**: Extract and aggregate normalized domain mentions (combining domains found in `websiteRankings[].domain` and the `domain` field of the `fanout.sources[]` array) grouped by each time period derived from `updatedAt`. If `truncated.fanoutSourcesPreview` is true, fetch the full list of fanout sources from `GET /v2/runs/{runId}/results/{resultId}/fanout-sources` to obtain all domains.
2. **Growth Rate Calculation**: Compute the period-over-period growth rate of citation shares for each domain:
   $$\text{growthRate} = \frac{\text{share}_{\text{current}} - \text{share}_{\text{prior}}}{\text{share}_{\text{prior}}} \times 100$$
3. **Momentum Labeling**: Classify each domain's citation trend using the calculated growth rates:
   - `accelerating`: Significant positive growth rate trend across periods.
   - `stable`: Minor variation or stable period-over-period trend.
   - `declining`: Significant negative growth rate trend across periods.
4. **Concentration Over Time**: Track how domain concentration (e.g., Herfindahl-Hirschman Index or top 3 domains share) shifts over time.

## Expected Output

The skill must generate two outputs in the local workspace:

1. **`citation-momentum.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, `domain_momentum_table` data, lists of top gainers and decliners, concentration over time metrics, confidence metrics, and the evidence map.

2. **`citation-momentum.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Domain Momentum Leaderboard**: Formatted table with columns: `Domain | Current Share % | Growth Rate % | Momentum Label` sorted by growth rate.
   - **Top Gainers & Decliners**: Bulleted summaries representing `top_gainers[]` and `top_decliners[]`.
   - **Concentration Over Time**: Statement or timeline showing how overall citation market concentration is changing.
   - **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

- **Consistent Normalization**: Ensure all domain strings are normalized consistently (lowercase, stripped of protocols and subdomains where appropriate).
- **Minimum Sample Constraint**: Ignore any period that falls below the minimum required sample threshold (e.g. fewer than 10 total snapshot results in that period), and document the omitted data in the report.
- **No Web Lookups**: Do not perform external web lookups or enrichment of brand data.
- **No Hallucination**: Do not invent brands, rankings, websites, or trend values 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: Citation Momentum
Goal: Track citation share and growth by domain across periods.

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. `citation-momentum.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `citation-momentum.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)
- `websiteRankings[].domain` (string, domain name)
- `websiteRankings[].position` (integer, domain rank position)
- `fanout.sources[].domain` (string, fanout source domain)
- `truncated.fanoutSourcesPreview` (boolean, indicates if fanout sources are truncated inline)

Method:
Follow these step-by-step logic rules during analysis:
1. **Domain Mentions Grouping**: Extract and aggregate normalized domain mentions (combining domains found in `websiteRankings[].domain` and the `domain` field of the `fanout.sources[]` array) grouped by each time period derived from `updatedAt`. If `truncated.fanoutSourcesPreview` is true, fetch the full list of fanout sources from `GET /v2/runs/{runId}/results/{resultId}/fanout-sources` to obtain all domains.
2. **Growth Rate Calculation**: Compute the period-over-period growth rate of citation shares for each domain:
   $$\text{growthRate} = \frac{\text{share}_{\text{current}} - \text{share}_{\text{prior}}}{\text{share}_{\text{prior}}} \times 100$$
3. **Momentum Labeling**: Classify each domain's citation trend using the calculated growth rates:
   - `accelerating`: Significant positive growth rate trend across periods.
   - `stable`: Minor variation or stable period-over-period trend.
   - `declining`: Significant negative growth rate trend across periods.
4. **Concentration Over Time**: Track how domain concentration (e.g., Herfindahl-Hirschman Index or top 3 domains share) shifts over time.

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

1. **`citation-momentum.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, `domain_momentum_table` data, lists of top gainers and decliners, concentration over time metrics, confidence metrics, and the evidence map.

2. **`citation-momentum.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Domain Momentum Leaderboard**: Formatted table with columns: `Domain | Current Share % | Growth Rate % | Momentum Label` sorted by growth rate.
   - **Top Gainers & Decliners**: Bulleted summaries representing `top_gainers[]` and `top_decliners[]`.
   - **Concentration Over Time**: Statement or timeline showing how overall citation market concentration is changing.
   - **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:
- **Consistent Normalization**: Ensure all domain strings are normalized consistently (lowercase, stripped of protocols and subdomains where appropriate).
- **Minimum Sample Constraint**: Ignore any period that falls below the minimum required sample threshold (e.g. fewer than 10 total snapshot results in that period), and document the omitted data in the report.
- **No Web Lookups**: Do not perform external web lookups or enrichment of brand data.
- **No Hallucination**: Do not invent brands, rankings, websites, or trend values that are not present in the ingested dataset.
```