Entity Opportunity Finder

What it does

Identify and evaluate high-leverage related entities from AI description summaries and brand/recommendation lists, scoring entity relevance by frequency and keyword spread, and highlighting unowned opportunities.

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

• description (string, the detailed AI recommendation description containing entities)
• keyword (string, searched keyword)
• brandRankings[].name (string, brand name)
• brandRankings[].position (integer, brand rank position)
• productRankings[].name (string, product name)
• productRankings[].position (integer, product rank position)

Analytical Method

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

1. Entity Extraction & Normalization: Extract related entity names from description text (such as key technologies, integrations, features, or competitor brands mentioned in the recommendation) and clean them (lowercase comparison, trim noise, and remove common noise tokens like “the”, “inc”, “co”, “and”).
2. Frequency and Spread Aggregation: For each normalized entity, compute:
   • frequency: Total number of times the entity is mentioned across the entire dataset.
   • spread: The number of unique keywords/queries associated with the entity.
3. Entity Opportunity Scoring: Calculate an opportunity score combining frequency and spread: $$\text{opportunityScore} = w_1 \times \text{frequency} + w_2 \times \text{spread}$$
4. Unowned Opportunity Identification: Compare the identified entities against the list of brands present in brandRankings[].name and products in productRankings[].name. Any entity that is highly scored but has no associated rankings or products is categorized as an “unowned opportunity.”

Expected Output

The skill must generate two outputs in the local workspace:

1. entity-opportunity-finder.json: Contains the raw structured analytical output, including the execution contract metadata, entity_opportunities[] list, prioritized target actions, confidence metrics, and the evidence map.

2. entity-opportunity-finder.md: A premium, beautiful human-readable report. This report must contain:

   • Entity Opportunity Leaderboard: Summary table showing entity names, calculated opportunity score, frequency, and keyword spread.
   • Prioritization Actions: Detailed, high-leverage actions for targeting these unowned entities (e.g. content clusters to build, entities to associate with the brand).
   • 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 (e.g. noise tokens filtered).
   • Evidence Map: An array of objects evidence_map[] with:
     • finding_id
     • metric_name
     • source_field_paths[]
     • sample_result_ids[]

Guardrails & Constraints

• Noise Token Filtering: Strictly filter out common nouns, generic adjectives, and search engine noise tokens to prevent junk entities from dominating the leaderboard.
• Observed Entities Only: Only utilize entities that are explicitly observed in description or rankings. Do not invent or infer entities that are not present.
• No Web Lookups: Do not perform external web lookups or enrichment of brand data.
• No Hallucination: Do not invent brands, rankings, keywords, or timestamps 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: Entity Opportunity Finder
Goal: Identify high-leverage entities from description recommendations and brand lists.

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. `entity-opportunity-finder.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `entity-opportunity-finder.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:
- `description` (string, the detailed AI recommendation description containing entities)
- `keyword` (string, searched keyword)
- `brandRankings[].name` (string, brand name)
- `brandRankings[].position` (integer, brand rank position)
- `productRankings[].name` (string, product name)
- `productRankings[].position` (integer, product rank position)

Method:
Follow these step-by-step logic rules during analysis:
1. **Entity Extraction & Normalization**: Extract related entity names from `description` text (such as key technologies, integrations, features, or competitor brands mentioned in the recommendation) and clean them (lowercase comparison, trim noise, and remove common noise tokens like "the", "inc", "co", "and").
2. **Frequency and Spread Aggregation**: For each normalized entity, compute:
   - **`frequency`**: Total number of times the entity is mentioned across the entire dataset.
   - **`spread`**: The number of unique keywords/queries associated with the entity.
3. **Entity Opportunity Scoring**: Calculate an opportunity score combining frequency and spread:
   $$\text{opportunityScore} = w_1 \times \text{frequency} + w_2 \times \text{spread}$$
4. **Unowned Opportunity Identification**: Compare the identified entities against the list of brands present in `brandRankings[].name` and products in `productRankings[].name`. Any entity that is highly scored but has no associated rankings or products is categorized as an "unowned opportunity."

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

1. **`entity-opportunity-finder.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, `entity_opportunities[]` list, prioritized target actions, confidence metrics, and the evidence map.

2. **`entity-opportunity-finder.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Entity Opportunity Leaderboard**: Summary table showing entity names, calculated opportunity score, frequency, and keyword spread.
   - **Prioritization Actions**: Detailed, high-leverage actions for targeting these unowned entities (e.g. content clusters to build, entities to associate with the brand).
   - **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 (e.g. noise tokens filtered).
   - **Evidence Map**: An array of objects `evidence_map[]` with:
     - `finding_id`
     - `metric_name`
     - `source_field_paths[]`
     - `sample_result_ids[]`

Guardrails:
- **Noise Token Filtering**: Strictly filter out common nouns, generic adjectives, and search engine noise tokens to prevent junk entities from dominating the leaderboard.
- **Observed Entities Only**: Only utilize entities that are explicitly observed in `description` or rankings. Do not invent or infer entities that are not present.
- **No Web Lookups**: Do not perform external web lookups or enrichment of brand data.
- **No Hallucination**: Do not invent brands, rankings, keywords, or timestamps that are not present in the ingested dataset.