New Entrant Detector

What it does

Detect and track brand newcomers entering the top N ranking positions over multiple snapshot periods, measuring their consecutive presence persistence and scoring entrant strength.

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 https://api.fullmention.com/v1/results/latest.
• 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.
• Local Persistence: Save all analytical outputs locally in the current workspace directory.
  • Raw structured JSON must be saved to [skill_name].json (e.g. new-entrant-detector.json).
  • A premium, beautifully styled markdown report must be saved to [skill_name].md (e.g. new-entrant-detector.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:

• updatedAt (string, ISO-8601 timestamp of snapshot update)
• keyword (string, searched keyword)
• brandRankings[].name (string, brand name)
• brandRankings[].position (integer, brand rank position)

Input Parameters:

• topN (integer, default: 20; rank threshold for entry evaluation)
• minPersistencePeriods (integer, default: 2; minimum consecutive periods to count as persistent)

Analytical Method

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

1. Snapshots Chronology: Sort the ingested snapshots by updatedAt in ascending order.
2. Top N Entry Analysis: For each period, identify brands appearing within the top N positions (position <= topN).
3. First Appearance Identification: Identify the period in which a brand first appears within the top N.
4. Persistence Tracking:
   • Count the number of consecutive subsequent periods the brand remains within the top N starting from their first appearance.
   • Distinguish a true new entrant (first time appearing in top N in the series) from a returning brand (a brand that appeared in top N, disappeared, and returned after a gap).
5. Entrant Strength Scoring: Score the newcomer’s momentum based on a combination of their initial entry rank and persistence: $$\text{entrantStrength} = w_1 \times \left( \text{topN} - \text{entryRank} + 1 \right) + w_2 \times \text{consecutivePeriodsCount}$$

Expected Output

The skill must generate two outputs in the local workspace:

1. new-entrant-detector.json: Contains the raw structured analytical output, including the execution contract metadata, new_entrants[] list, calculated persistence scores, list of early winner candidates, confidence metrics, and the evidence map.

2. new-entrant-detector.md: A premium, beautiful human-readable report. This report must contain:

   • New Entrants Leaderboard: Summary table showing brand names, keyword, period of first appearance, entry rank, consecutive periods retained, and Entrant Strength Score.
   • Persistence Metrics: Highlight of overall brand retention and persistence_score for the cohort.
   • Early Winner Candidates: High-potential newcomers with high entry ranks and persistent visibility.
   • 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

• Returning Brands Discrimination: Explicitly separate returning brands (returning after a gap) from true new entrants in your reports.
• No Long-term Predictions: Restrict reports to factual historical persistence and short-term trends. Do not make long-term success prediction claims.
• 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: New Entrant Detector
Goal: Detect new brands entering top N and measure persistence.

Data Access Policy:
- **API Target**: Consume data from the FullMention API at `https://api.fullmention.com/v1/results/latest`.
- **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.
- **Local Persistence**: Save all analytical outputs locally in the current workspace directory.
  - Raw structured JSON must be saved to `[skill_name].json` (e.g. `new-entrant-detector.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `new-entrant-detector.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:
- `updatedAt` (string, ISO-8601 timestamp of snapshot update)
- `keyword` (string, searched keyword)
- `brandRankings[].name` (string, brand name)
- `brandRankings[].position` (integer, brand rank position)

Input Parameters:
- `topN` (integer, default: 20; rank threshold for entry evaluation)
- `minPersistencePeriods` (integer, default: 2; minimum consecutive periods to count as persistent)

Method:
Follow these step-by-step logic rules during analysis:
1. **Snapshots Chronology**: Sort the ingested snapshots by `updatedAt` in ascending order.
2. **Top N Entry Analysis**: For each period, identify brands appearing within the top N positions (`position <= topN`).
3. **First Appearance Identification**: Identify the period in which a brand first appears within the top N.
4. **Persistence Tracking**:
   - Count the number of consecutive subsequent periods the brand remains within the top N starting from their first appearance.
   - Distinguish a true new entrant (first time appearing in top N in the series) from a returning brand (a brand that appeared in top N, disappeared, and returned after a gap).
5. **Entrant Strength Scoring**: Score the newcomer's momentum based on a combination of their initial entry rank and persistence:
   $$\text{entrantStrength} = w_1 \times \left( \text{topN} - \text{entryRank} + 1 \right) + w_2 \times \text{consecutivePeriodsCount}$$

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

1. **`new-entrant-detector.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, `new_entrants[]` list, calculated persistence scores, list of early winner candidates, confidence metrics, and the evidence map.

2. **`new-entrant-detector.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **New Entrants Leaderboard**: Summary table showing brand names, keyword, period of first appearance, entry rank, consecutive periods retained, and Entrant Strength Score.
   - **Persistence Metrics**: Highlight of overall brand retention and `persistence_score` for the cohort.
   - **Early Winner Candidates**: High-potential newcomers with high entry ranks and persistent visibility.
   - **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:
- **Returning Brands Discrimination**: Explicitly separate returning brands (returning after a gap) from true new entrants in your reports.
- **No Long-term Predictions**: Restrict reports to factual historical persistence and short-term trends. Do not make long-term success prediction claims.
- **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.