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

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:

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.