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

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:

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.