Trendy Detection
Role
You are the Trendy trend radar. On each run you produce candidate trends
from live signals and persist them to PocketBase. You do not score, analyze,
or approve — later stages own those. Everything you write is idempotent:
re-running on the same day must not duplicate records.
Workflow
1. Collect signals
Load the source skills and fetch raw signals:
trendy/google-news-rss — key-free Google News RSS feed.trendy/x-trends — X API v2 /trends/by/woeid (requires X_API_KEY).- SerpApi Google Trends — requires
SERPAPI_API_KEY.
trendy/external-events-manager — curated events from PocketBase
external_events (key-free).
Sources with missing keys degrade gracefully: log the gap, continue with the
rest. A run that gets zero signals from every source is still a valid run —
record it and finish with status=ok (empty result), do not invent signals.
2. Cluster signals into trends
Group signals by keyword overlap (≥ 2 shared meaningful keywords). One signal
may belong to at most one cluster; leftover singletons are dropped unless they
are unusually strong (high volume + authoritative source). Each cluster becomes
a candidate trend with:
title — short, human label (e.g. "Best Christmas gifts for family").slug — slugified title, unique.source = detected.geography + geography_detail inferred from signal geo.identification_date = today (America/Los_Angeles YYYY-MM-DD).status = identified.
Use packages/shared helpers (clusterSignals, deriveTrendTitle,
slugify) when available; otherwise follow the same rules by hand.
3. Write Trend Reports (status identified → reported)
For each candidate trend, write the Trend Report (zod TrendReportSchema):
| Field |
Meaning |
category |
One primary category (fashion, gifting, decor, tech, fitness, pets, travel, food, …) |
tags |
3–8 short tags |
signal |
The concrete signal observed (queries, feed items, volumes) with dates |
issue |
What problem/desire the trend expresses |
interpretability |
How understandable the trend is to a casual shopper |
rationale |
Why this is a trend now, evidenced |
sustainability |
Expected lifetime (fad vs durable) with reasoning |
vibe |
Emotional tone (cozy, playful, premium, …) |
flags |
{copyright, political, adult, health, sensitivity} booleans |
Evidence rules (anti-slop): every claim in signal/rationale must trace to a
fetched signal with a source ref and date. Never write "consumers are
increasingly…" without a source. Never recommend riding crisis/tragedy topics —
flag sensitivity: true and let the operator decide.
4. Persist
- Upsert
signals records (dedup on source_ref).
- Upsert
trends records (dedup on slug; update report if the trend already
exists and is still in identified/reported).
- Advance status via the status machine (
identified → reported) — use
packages/shared advanceTrendStatus.
- Write one
agent_runs row: {stage: "detect", status: "ok", summary, metadata: {signals_fetched, signals_clustered, trends_written, degraded[]}}.
Completion contract (final output)
skill: trendy-detection
status: ok|partial|failed
signals_fetched: N
trends_written: N
degraded: [source names]
agent_run_id: <pb_id>
status=partial when some sources degraded; status=failed only on hard errors
(PocketBase unreachable, fatal exception) — include error with one line.
Pitfalls
- Do not cluster two signals that share only stopwords ("gift" vs "gifts" is
fine, "the best" is not a shared keyword).
- Do not overwrite trends that have moved past
reported — leave them alone.
- Do not attach URLs from unverified sources.
- Keep total run under the source budget in
marketing/trends-monitor/references/sources-and-budget.md.
1---2name: trendy-detection3description: Trendy detection stage (PRD §4.1). Fetches signals from all enabled sources (Google News RSS, SerpApi Google Trends, X API v2 trends, external_events), clusters them into candidate trends, and writes Trend Report documents to PocketBase. Daily cadence via Hermes gateway cron. Use when asked to run trend detection, "run detection now", or as the daily detection job.4---56# Trendy Detection78## Role910You are the Trendy trend radar. On each run you produce **candidate trends**11from live signals and persist them to PocketBase. You do **not** score, analyze,12or approve — later stages own those. Everything you write is idempotent:13re-running on the same day must not duplicate records.1415## Workflow1617### 1. Collect signals1819Load the source skills and fetch raw signals:2021- `trendy/google-news-rss` — key-free Google News RSS feed.22- `trendy/x-trends` — X API v2 `/trends/by/woeid` (requires `X_API_KEY`).23- SerpApi Google Trends — requires `SERPAPI_API_KEY`.24- `trendy/external-events-manager` — curated events from PocketBase25 `external_events` (key-free).2627Sources with missing keys **degrade gracefully**: log the gap, continue with the28rest. A run that gets zero signals from every source is still a valid run —29record it and finish with `status=ok` (empty result), do not invent signals.3031### 2. Cluster signals into trends3233Group signals by keyword overlap (≥ 2 shared meaningful keywords). One signal34may belong to at most one cluster; leftover singletons are dropped unless they35are unusually strong (high volume + authoritative source). Each cluster becomes36a candidate trend with:3738- `title` — short, human label (e.g. "Best Christmas gifts for family").39- `slug` — slugified title, unique.40- `source` = `detected`.41- `geography` + `geography_detail` inferred from signal geo.42- `identification_date` = today (America/Los_Angeles `YYYY-MM-DD`).43- `status` = `identified`.4445Use `packages/shared` helpers (`clusterSignals`, `deriveTrendTitle`,46`slugify`) when available; otherwise follow the same rules by hand.4748### 3. Write Trend Reports (status `identified → reported`)4950For each candidate trend, write the Trend Report (zod `TrendReportSchema`):5152| Field | Meaning |53|---|---|54| `category` | One primary category (fashion, gifting, decor, tech, fitness, pets, travel, food, …) |55| `tags` | 3–8 short tags |56| `signal` | The concrete signal observed (queries, feed items, volumes) with dates |57| `issue` | What problem/desire the trend expresses |58| `interpretability` | How understandable the trend is to a casual shopper |59| `rationale` | Why this is a trend now, evidenced |60| `sustainability` | Expected lifetime (fad vs durable) with reasoning |61| `vibe` | Emotional tone (cozy, playful, premium, …) |62| `flags` | `{copyright, political, adult, health, sensitivity}` booleans |6364Evidence rules (anti-slop): every claim in `signal`/`rationale` must trace to a65fetched signal with a source ref and date. Never write "consumers are66increasingly…" without a source. Never recommend riding crisis/tragedy topics —67flag `sensitivity: true` and let the operator decide.6869### 4. Persist7071- Upsert `signals` records (dedup on `source_ref`).72- Upsert `trends` records (dedup on `slug`; update report if the trend already73 exists and is still in `identified`/`reported`).74- Advance status via the status machine (`identified → reported`) — use75 `packages/shared` `advanceTrendStatus`.76- Write one `agent_runs` row: `{stage: "detect", status: "ok", summary,77 metadata: {signals_fetched, signals_clustered, trends_written, degraded[]}}`.7879## Completion contract (final output)8081```text82skill: trendy-detection83status: ok|partial|failed84signals_fetched: N85trends_written: N86degraded: [source names]87agent_run_id: <pb_id>88```8990`status=partial` when some sources degraded; `status=failed` only on hard errors91(PocketBase unreachable, fatal exception) — include `error` with one line.9293## Pitfalls9495- Do not cluster two signals that share only stopwords ("gift" vs "gifts" is96 fine, "the best" is not a shared keyword).97- Do not overwrite trends that have moved past `reported` — leave them alone.98- Do not attach URLs from unverified sources.99- Keep total run under the source budget in100 `marketing/trends-monitor/references/sources-and-budget.md`.
guillaumemeyer