---
title: "Gap Analysis"
description: "Detect opportunity gaps for a target brand."
order: 3
featured: false
---

   
                     
                                                          
        
   
# Gap Analysis

## What it does

Detect competitive opportunity gaps for a target brand by identifying keywords where only competitors are visible, calculating competitive pressure, and recommending actionable marketing strategies.

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

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

## Analytical Method

Follow these step-by-step logic rules during analysis:
1. **Presence Mapping**: For each keyword in the dataset, identify the presence of both the `targetBrand` and the brands listed in `competitorBrands[]` within the brand rankings (`brandRankings[]`).
2. **Gap Identification**: Filter the list of keywords to identify "competitor-only" keywords. A keyword is a gap keyword if at least one brand in `competitorBrands[]` is present (in `brandRankings[]`) and the `targetBrand` is completely absent.
3. **Pressure Scoring**: For each identified gap keyword, calculate a competitive pressure score using the sum of the reciprocal positions of all competitor mentions:
   $$\text{pressureScore} = \sum \frac{1}{\text{position}}$$
   *(If a competitor brand has multiple mentions, aggregate their weights).*
4. **Ranking & Prioritization**: Sort the identified gap keywords in descending order of their `pressureScore`.

## Expected Output

The skill must generate two outputs in the local workspace:

1. **`gap-analysis.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, sorted gap keywords with pressure scores and top competitors, 3-5 recommended actions, confidence metrics, and the evidence map.

2. **`gap-analysis.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Gap Keywords Leaderboard**: Formatted table with columns: `Keyword | Pressure Score | Top Competitor | Key Mentions` sorted in descending order of `Pressure Score`.
   - **Recommended Actions**: 3 to 5 clear, tactical, and actionable steps for the target brand to bridge the identified gaps (e.g. targeted ad campaigns, content optimizations, partnership suggestions).
   - **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 Extraneous Causal Claims**: Restrict findings to objective observations. Do not make causal claims beyond observed presence (e.g. do not assume why a competitor is ranking high or why target brand is absent without explicit data).
- **No Web Lookups**: Do not perform external web lookups or enrichment of brand data.
- **No Hallucination**: Do not invent brands, keywords, 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:

```text
Skill: Gap Analysis
Goal: Detect opportunity gaps for a target brand.

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. `gap-analysis.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `gap-analysis.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.

The input dataset from the API/file must map to these fields:
- `keyword` (string, searched keyword)
- `brandRankings[].name` (string, brand name)
- `brandRankings[].position` (integer, brand rank position)

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

Method:
Follow these step-by-step logic rules during analysis:
1. **Presence Mapping**: For each keyword in the dataset, identify the presence of both the `targetBrand` and the brands listed in `competitorBrands[]` within the brand rankings (`brandRankings[]`).
2. **Gap Identification**: Filter the list of keywords to identify "competitor-only" keywords. A keyword is a gap keyword if at least one brand in `competitorBrands[]` is present (in `brandRankings[]`) and the `targetBrand` is completely absent.
3. **Pressure Scoring**: For each identified gap keyword, calculate a competitive pressure score using the sum of the reciprocal positions of all competitor mentions:
   $$\text{pressureScore} = \sum \frac{1}{\text{position}}$$
   *(If a competitor brand has multiple mentions, aggregate their weights).*
4. **Ranking & Prioritization**: Sort the identified gap keywords in descending order of their `pressureScore`.

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

1. **`gap-analysis.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, sorted gap keywords with pressure scores and top competitors, 3-5 recommended actions, confidence metrics, and the evidence map.

2. **`gap-analysis.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Gap Keywords Leaderboard**: Formatted table with columns: `Keyword | Pressure Score | Top Competitor | Key Mentions` sorted in descending order of `Pressure Score`.
   - **Recommended Actions**: 3 to 5 clear, tactical, and actionable steps for the target brand to bridge the identified gaps (e.g. targeted ad campaigns, content optimizations, partnership suggestions).
   - **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 Extraneous Causal Claims**: Restrict findings to objective observations. Do not make causal claims beyond observed presence (e.g. do not assume why a competitor is ranking high or why target brand is absent without explicit data).
- **No Web Lookups**: Do not perform external web lookups or enrichment of brand data.
- **No Hallucination**: Do not invent brands, keywords, rankings, or hidden fields that are not present in the ingested dataset.
```