Competitor Citation Advantage

What it does

Quantify citation coverage advantages and disadvantages by domain for a target brand compared against a list of competitor brands, and identify high-priority citation gaps.

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. competitor-citation-advantage.json).
  • A premium, beautifully styled markdown report must be saved to [skill_name].md (e.g. competitor-citation-advantage.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:

• websiteRankings[].domain (string, domain name)
• websiteRankings[].position (integer, domain rank position)
• brandRankings[].name (string, brand name)
• brandRankings[].position (integer, brand rank position)
• keyword (string, searched keyword)

Input Parameters:

• targetBrand (string, normalized name of the target brand)
• competitorBrands[] (array of strings, list of competitor brand names to compare against)

Analytical Method

Follow these step-by-step logic rules during analysis:

1. Domain coverage construction: For each unique domain in websiteRankings[].domain, calculate the citation coverage percentage for the targetBrand and each brand in competitorBrands[]. $$\text{brandCoverage} = \frac{\text{results where domain ranks brand}}{\text{total results containing domain}} \times 100$$
2. Advantage Index calculation: For each domain, compute the advantage index of the target brand compared to the average of its competitors: $$\text{advantageIndex} = \text{targetCoverage} - \text{competitorCoverageAvg}$$
3. Domain Labeling: Classify each domain into one of the following strategic labels:
   • defend: The target brand has a positive advantage index ($\text{advantageIndex} > 10$), indicating a strong citation lead that must be maintained.
   • gap: The target brand has a negative advantage index ($\text{advantageIndex} < -10$) while competitors are strongly cited, representing a critical gap to bridge.
   • neutral: The advantage index is stable and near zero (between $-10$ and $10$).

Expected Output

The skill must generate two outputs in the local workspace:

1. competitor-citation-advantage.json: Contains the raw structured analytical output, including the execution contract metadata, domain advantage matrix with advantage index scores, lists of high-priority gap domains, confidence metrics, and the evidence map.

2. competitor-citation-advantage.md: A premium, beautiful human-readable report. This report must contain:

   • Domain Advantage Matrix: Formatted table showing domains, target brand coverage %, competitor average coverage %, advantage index, and strategic label (Defend | Gap | Neutral).
   • Priority Gap Domains: Actionable list of domains where the target brand has a substantial disadvantage and competitor visibility is highest.
   • 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

• No Causal Inferences: Restrict findings strictly to calculated coverage deltas. Do not infer or assume the causes of these differences (e.g. sponsorship, content quality) without explicit data.
• Normalize Domains Consistent: Ensure all domain strings are normalized consistently (lowercase, stripped of protocols and subdomains where appropriate).
• 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: Competitor Citation Advantage
Goal: Quantify citation edge by domain.

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. `competitor-citation-advantage.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `competitor-citation-advantage.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:
- `websiteRankings[].domain` (string, domain name)
- `websiteRankings[].position` (integer, domain rank position)
- `brandRankings[].name` (string, brand name)
- `brandRankings[].position` (integer, brand rank position)
- `keyword` (string, searched keyword)

Input Parameters:
- `targetBrand` (string, normalized name of the target brand)
- `competitorBrands[]` (array of strings, list of competitor brand names to compare against)

Method:
Follow these step-by-step logic rules during analysis:
1. **Domain coverage construction**: For each unique domain in `websiteRankings[].domain`, calculate the citation coverage percentage for the `targetBrand` and each brand in `competitorBrands[]`.
   $$\text{brandCoverage} = \frac{\text{results where domain ranks brand}}{\text{total results containing domain}} \times 100$$
2. **Advantage Index calculation**: For each domain, compute the advantage index of the target brand compared to the average of its competitors:
   $$\text{advantageIndex} = \text{targetCoverage} - \text{competitorCoverageAvg}$$
3. **Domain Labeling**: Classify each domain into one of the following strategic labels:
   - `defend`: The target brand has a positive advantage index ($\text{advantageIndex} > 10$), indicating a strong citation lead that must be maintained.
   - `gap`: The target brand has a negative advantage index ($\text{advantageIndex} < -10$) while competitors are strongly cited, representing a critical gap to bridge.
   - `neutral`: The advantage index is stable and near zero (between $-10$ and $10$).

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

1. **`competitor-citation-advantage.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, domain advantage matrix with advantage index scores, lists of high-priority gap domains, confidence metrics, and the evidence map.

2. **`competitor-citation-advantage.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Domain Advantage Matrix**: Formatted table showing domains, target brand coverage %, competitor average coverage %, advantage index, and strategic label (Defend | Gap | Neutral).
   - **Priority Gap Domains**: Actionable list of domains where the target brand has a substantial disadvantage and competitor visibility is highest.
   - **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:
- **No Causal Inferences**: Restrict findings strictly to calculated coverage deltas. Do not infer or assume the causes of these differences (e.g. sponsorship, content quality) without explicit data.
- **Normalize Domains Consistent**: Ensure all domain strings are normalized consistently (lowercase, stripped of protocols and subdomains where appropriate).
- **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.