---
title: "Citation Coverage"
description: "Rank cited domains from recommendation websites and optional fanout sources."
order: 5
featured: false
---

   
                          
                                                                                           
        
   
# Citation Coverage

## What it does

Rank and evaluate cited domains from recommendation websites and optional fanout sources, calculating domain strength scores, citation coverage, and classification concentration metrics.

## 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-coverage.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `citation-coverage.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:
- `id` (string, unique result identifier)
- `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 Extraction & Normalization**: Extract domains from `websiteRankings[].domain` and clean them (e.g., convert to lowercase, strip `www.`, protocol prefixes, and trailing slashes).
2. **Domain Aggregation**: Aggregate the count of mentions for each normalized domain across the dataset (combining domains found in `websiteRankings[].domain` and the `domain` field of `fanout.sources[]`). 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.
3. **Coverage Computation**: Compute the coverage percentage for each domain across all results:
   $$\text{coveragePercent} = \frac{\text{results containing domain}}{\text{total results}} \times 100$$
4. **Combined Strength Score Ranking**: Calculate a combined domain strength score and rank the domains:
   $$\text{strength} = w_1 \times \text{mentionCount} + w_2 \times \text{coveragePercent}$$
   *(Set reasonable weights $w_1, w_2$ depending on data presence).*
5. **Concentration Classification**: Classify the overall domain concentration into one of the following classes:
   - `high`: A small number of dominant domains hold the vast majority of citations.
   - `balanced`: Citations are evenly distributed across a healthy mix of different domains.
   - `fragmented`: Citations are heavily spread out across many unique domains with no clear leaders.

## Expected Output

The skill must generate two outputs in the local workspace:

1. **`citation-coverage.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, domain leaderboard with mention counts, coverage percentages, and strength scores, the concentration classification, confidence metrics, and the evidence map.

2. **`citation-coverage.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Domain Leaderboard**: Formatted table with columns: `Domain | Mention Count | Coverage % | Strength Score`.
   - **Concentration Analysis**: Statement and discussion of the `concentration class` (high | balanced | fragmented).
   - **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).
- **Exclude Empty Domains**: Do not count, report, or include empty or invalid domains.
- **No External Crawling**: Strictly avoid any external HTTP crawling or fetching of the identified domains. Operate entirely offline on the ingested snapshot data.

## Copy-ready Skill Prompt

Use this as a full copy/paste prompt in your AI tool:

```text
Skill: Citation Coverage
Goal: Rank cited domains from recommendation websites and optional fanout sources.

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-coverage.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `citation-coverage.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:
- `id` (string, unique result identifier)
- `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 Extraction & Normalization**: Extract domains from `websiteRankings[].domain` and clean them (e.g., convert to lowercase, strip `www.`, protocol prefixes, and trailing slashes).
2. **Domain Aggregation**: Aggregate the count of mentions for each normalized domain across the dataset (combining domains found in `websiteRankings[].domain` and the `domain` field of `fanout.sources[]`). 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.
3. **Coverage Computation**: Compute the coverage percentage for each domain across all results:
   $$\text{coveragePercent} = \frac{\text{results containing domain}}{\text{total results}} \times 100$$
4. **Combined Strength Score Ranking**: Calculate a combined domain strength score and rank the domains:
   $$\text{strength} = w_1 \times \text{mentionCount} + w_2 \times \text{coveragePercent}$$
   *(Set reasonable weights $w_1, w_2$ depending on data presence).*
5. **Concentration Classification**: Classify the overall domain concentration into one of the following classes:
   - `high`: A small number of dominant domains hold the vast majority of citations.
   - `balanced`: Citations are evenly distributed across a healthy mix of different domains.
   - `fragmented`: Citations are heavily spread out across many unique domains with no clear leaders.

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

1. **`citation-coverage.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, domain leaderboard with mention counts, coverage percentages, and strength scores, the concentration classification, confidence metrics, and the evidence map.

2. **`citation-coverage.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Domain Leaderboard**: Formatted table with columns: `Domain | Mention Count | Coverage % | Strength Score`.
   - **Concentration Analysis**: Statement and discussion of the `concentration class` (high | balanced | fragmented).
   - **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).
- **Exclude Empty Domains**: Do not count, report, or include empty or invalid domains.
- **No External Crawling**: Strictly avoid any external HTTP crawling or fetching of the identified domains. Operate entirely offline on the ingested snapshot data.
```