Share Of Voice Trend

What it does

Analyze brand Share of Voice (SOV) trends over time by building period-by-period time series, computing trend slopes and momentum, and identifying key inflection points.

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

Analytical Method

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

Period SOV Computation: For each defined time period (day or week), calculate the SOV for each brand using the reciprocal position formula in brandRankings[]: $$\text{weightedScore} = \sum \frac{1}{\text{position}}$$ Convert each brand’s score to a percentage of the total weighted score within that specific period.
Time-Series Construction: Assemble a chronological time-series of SOV percentages for each brand across all available periods.
Slope and Momentum Analysis:
- Trend Slope: Calculate the linear slope (rate of change) of the SOV percentage for each brand across the time-series.
- Momentum Delta: Calculate the change between the last 2-3 periods.
- Momentum Label: Classify the brand’s current momentum trend as:
  - rising: Clear positive slope and upward delta in recent periods.
  - flat: Minimal change (slope near zero).
  - falling: Clear negative slope and downward delta in recent periods.
Inflection Points: Identify key inflection points where a brand’s trend direction changed significantly (e.g., from falling to rising).

Expected Output

The skill must generate two outputs in the local workspace:

share-of-voice-trend.json: Contains the raw structured analytical output, including the execution contract metadata, sov_trend_series[], calculated slopes by brand, momentum labels, identified inflection points, confidence metrics, and the evidence map.
share-of-voice-trend.md: A premium, beautiful human-readable report. This report must contain:
- SOV Trend Leaderboard: Summary table showing brand names, slope, current momentum label, and recent SOV percentages.
- Trend Series Details: Chronological breakdown or timeline representing sov_trend_series[].
- Key Inflection Points: Narrative or bulleted list of significant shifts in brand visibility over time.
- 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

Minimum Period Constraint: Stable slope calculation and momentum tracking require at least 4 periods of historical data. If fewer than 4 periods are available, flag low confidence and explain this constraint clearly.
No Extraneous Causal Claims: Restrict findings to mathematical observations of visibility trends. Do not hypothesize about external causal factors (e.g. ad spend, product changes) without explicit data backing.
No Web Lookups: Do not perform external web lookups or enrichment of brand data.
No Hallucination: Do not invent brands, timestamps, rankings, or trend values 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: Share Of Voice Trend
Goal: Measure SOV trend per brand over time.

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

Method:
Follow these step-by-step logic rules during analysis:
1. **Period SOV Computation**: For each defined time period (day or week), calculate the SOV for each brand using the reciprocal position formula in `brandRankings[]`:
   $$\text{weightedScore} = \sum \frac{1}{\text{position}}$$
   Convert each brand's score to a percentage of the total weighted score within that specific period.
2. **Time-Series Construction**: Assemble a chronological time-series of SOV percentages for each brand across all available periods.
3. **Slope and Momentum Analysis**:
   - **Trend Slope**: Calculate the linear slope (rate of change) of the SOV percentage for each brand across the time-series.
   - **Momentum Delta**: Calculate the change between the last 2-3 periods.
   - **Momentum Label**: Classify the brand's current momentum trend as:
     - `rising`: Clear positive slope and upward delta in recent periods.
     - `flat`: Minimal change (slope near zero).
     - `falling`: Clear negative slope and downward delta in recent periods.
4. **Inflection Points**: Identify key inflection points where a brand's trend direction changed significantly (e.g., from falling to rising).

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

1. **`share-of-voice-trend.json`**:
   Contains the raw structured analytical output, including the execution contract metadata, `sov_trend_series[]`, calculated slopes by brand, momentum labels, identified inflection points, confidence metrics, and the evidence map.

2. **`share-of-voice-trend.md`**:
   A premium, beautiful human-readable report. This report must contain:
   - **SOV Trend Leaderboard**: Summary table showing brand names, slope, current momentum label, and recent SOV percentages.
   - **Trend Series Details**: Chronological breakdown or timeline representing `sov_trend_series[]`.
   - **Key Inflection Points**: Narrative or bulleted list of significant shifts in brand visibility over time.
   - **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:
- **Minimum Period Constraint**: Stable slope calculation and momentum tracking require at least 4 periods of historical data. If fewer than 4 periods are available, flag low confidence and explain this constraint clearly.
- **No Extraneous Causal Claims**: Restrict findings to mathematical observations of visibility trends. Do not hypothesize about external causal factors (e.g. ad spend, product changes) without explicit data backing.
- **No Web Lookups**: Do not perform external web lookups or enrichment of brand data.
- **No Hallucination**: Do not invent brands, timestamps, rankings, or trend values that are not present in the ingested dataset.