Alerting Rules Engine

What it does

Evaluate brand visibility changes, rank drops, and brand disappearances between the latest and prior result snapshots, and emit structured severity-based alerts with full evidence backing.

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. alerting-rules-engine.json).
  • A premium, beautifully styled markdown report must be saved to [skill_name].md (e.g. alerting-rules-engine.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)
• websiteRankings[].domain (string, domain name)
• websiteRankings[].position (integer, domain rank position)
• productRankings[].name (string, product name)
• productRankings[].position (integer, product rank position)
• updatedAt (string, ISO-8601 timestamp of snapshot update)

Input Parameters:

• alertConfig (object, optional parameters to customize thresholds for rank drops, disappearances, and severities)

Analytical Method

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

1. Snapshot Ordering: Sort the ingested snapshots by updatedAt in descending order. Identify the latest snapshot and compare it against the immediate prior snapshot in the sequence.
2. Disappearance Detection:
   • Brands: Identify brands present in the prior snapshot’s brandRankings[] but absent from the latest snapshot.
   • Domains: Identify domains present in the prior snapshot’s websiteRankings[] but absent from the latest snapshot.
   • Products: Identify products present in the prior snapshot’s productRankings[] but absent from the latest snapshot.
3. Rank-Drop Evaluation: For brands, domains, or products present in both snapshots for a given keyword, calculate the position difference: $$\Delta_{\text{position}} = \text{position}{\text{latest}} - \text{position}{\text{prior}}$$ (A positive value indicates a drop in position, e.g., dropping from Position 2 to Position 8 is a +6 drop).
4. Severity Assignment:
   • Critical: Entire disappearance of a brand, domain, or product that ranked in the top 5 previously, or a position drop of $\Delta_{\text{position}} \ge 5$ for any entity previously in the top 5.
   • Warning: Moderate position drops ($3 \le \Delta_{\text{position}} \le 4$ positions), or disappearance of a mid-tier entity (previously ranked 6-15).
   • Info: Minor position drops ($1 \le \Delta_{\text{position}} \le 2$ positions), or disappearance of a low-visibility entity (previously ranked >15).
5. Evidence Compilation: Collect the precise data payload (keyword, entity type, name/domain, prior position, latest position, result IDs) to back up every generated alert.

Expected Output

The skill must generate two outputs in the local workspace:

1. alerting-rules-engine.json: Contains the raw structured analytical output, including the execution contract metadata, full list of generated alerts with severities and structured evidence payloads, confidence metrics, and the evidence map.

2. alerting-rules-engine.md: A premium, beautiful human-readable report. This report must contain:

   • Alert Inbox/Overview: A summary table showing the count of alerts by severity (Critical, Warning, Info).
   • Active Alert List: Detailed list of all triggered alerts, sorted by severity (highest first), including:
     • Severity (Critical | Warning | Info)
     • Message (e.g. “Brand [X] dropped from Position 2 to 8 for keyword ‘[Y]’.”, “Domain [Z] disappeared for keyword ‘[Y]’.”)
     • Evidence (entity type, name/domain, prior position, current position, and result/snapshot identifiers)
   • 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 Alerts Without Evidence: It is strictly forbidden to emit any alert that is not backed by objective, verifiable data in the comparison dataset. Every alert must include a traceable evidence payload.
• 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 comparison snapshots.

Copy-ready Skill Prompt

Use this as a full copy/paste prompt in your AI tool:

Skill: Alerting Rules Engine
Goal: Emit alerts from latest vs prior snapshot comparison.

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. `alerting-rules-engine.json`).
  - A premium, beautifully styled markdown report must be saved to `[skill_name].md` (e.g. `alerting-rules-engine.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:
- `keyword` (string, searched keyword)
- `brandRankings[].name` (string, brand name)
- `brandRankings[].position` (integer, brand rank position)
- `websiteRankings[].domain` (string, domain name)
- `websiteRankings[].position` (integer, domain rank position)
- `productRankings[].name` (string, product name)
- `productRankings[].position` (integer, product rank position)
- `updatedAt` (string, ISO-8601 timestamp of snapshot update)

Input Parameters:
- `alertConfig` (object, optional parameters to customize thresholds for rank drops, disappearances, and severities)

Method:
Follow these step-by-step logic rules during analysis:
1. **Snapshot Ordering**: Sort the ingested snapshots by `updatedAt` in descending order. Identify the latest snapshot and compare it against the immediate prior snapshot in the sequence.
2. **Disappearance Detection**:
   - **Brands**: Identify brands present in the prior snapshot's `brandRankings[]` but absent from the latest snapshot.
   - **Domains**: Identify domains present in the prior snapshot's `websiteRankings[]` but absent from the latest snapshot.
   - **Products**: Identify products present in the prior snapshot's `productRankings[]` but absent from the latest snapshot.
3. **Rank-Drop Evaluation**: For brands, domains, or products present in both snapshots for a given keyword, calculate the position difference:
   $$\Delta_{\text{position}} = \text{position}_{\text{latest}} - \text{position}_{\text{prior}}$$
   *(A positive value indicates a drop in position, e.g., dropping from Position 2 to Position 8 is a +6 drop).*
4. **Severity Assignment**:
   - **Critical**: Entire disappearance of a brand, domain, or product that ranked in the top 5 previously, or a position drop of $\Delta_{\text{position}} \ge 5$ for any entity previously in the top 5.
   - **Warning**: Moderate position drops ($3 \le \Delta_{\text{position}} \le 4$ positions), or disappearance of a mid-tier entity (previously ranked 6-15).
   - **Info**: Minor position drops ($1 \le \Delta_{\text{position}} \le 2$ positions), or disappearance of a low-visibility entity (previously ranked >15).
5. **Evidence Compilation**: Collect the precise data payload (keyword, entity type, name/domain, prior position, latest position, result IDs) to back up every generated alert.

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

1. **`alerting-rules-engine.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, full list of generated alerts with severities and structured evidence payloads, confidence metrics, and the evidence map.

2. **`alerting-rules-engine.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **Alert Inbox/Overview**: A summary table showing the count of alerts by severity (Critical, Warning, Info).
   - **Active Alert List**: Detailed list of all triggered alerts, sorted by severity (highest first), including:
     - `Severity` (Critical | Warning | Info)
     - `Message` (e.g. "Brand [X] dropped from Position 2 to 8 for keyword '[Y]'.", "Domain [Z] disappeared for keyword '[Y]'.")
     - `Evidence` (entity type, name/domain, prior position, current position, and result/snapshot identifiers)
   - **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 Alerts Without Evidence**: It is strictly forbidden to emit any alert that is not backed by objective, verifiable data in the comparison dataset. Every alert must include a traceable evidence payload.
- **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 comparison snapshots.