tinyfish-social-listening

What this skill does

# Social Listening with TinyFish

Track brand mentions, sentiment, and industry chatter across the live web — forums, blogs, news, social platforms, and developer communities — using TinyFish Search and Fetch.

**First step:** If the user already named the brand/topic, proceed directly. Otherwise, ask.
**Default time window:** Last 7 days.
**Always link every claim to its source URL.**

## When To Use

- User wants to know what people are saying about a brand, product, person, or topic.
- User asks to monitor competitors or compare share of voice.
- User wants sentiment analysis on a launch, feature, controversy, or trend.
- User says "social listening," "brand monitoring," "reputation check," "buzz check," or "what's the internet saying about X."
- User wants a recurring pulse on public perception (pair with a cron job).

## Pre-flight Check (REQUIRED)

```bash
# 1. TinyFish CLI installed?
which tinyfish && tinyfish --version || echo "TINYFISH_CLI_NOT_INSTALLED"

# 2. Authenticated?
tinyfish auth status
```

If CLI is not available, fall back to the TinyFish API with `TINYFISH_API_KEY`:

```bash
test -n "$TINYFISH_API_KEY" && echo "API_KEY_AVAILABLE" || echo "NO_TINYFISH_ACCESS"
```

If neither works, stop and tell the user to install or authenticate.

---

## Core Workflow

### Step 1 — Identify the target

If the user already named the brand/topic, skip asking and proceed. Otherwise, ask what brand, product, or topic they want to research. Then set:

- **Target entity:** Whatever the user specifies.
- **Time focus:** Last 7 days. All search queries MUST include date constraints.
- **Channels:** Reddit, Hacker News, Twitter/X, LinkedIn, blogs, news, GitHub, forums, YouTube.
- **Sentiment lens:** General pulse.

**⚠️ CRITICAL: STRICT 7-DAY ENFORCEMENT ⚠️**
Search engines regularly return results older than 7 days regardless of date constraints in queries. You MUST:
1. Check the `published_date` field on every fetched result
2. Check date indicators in Reddit posts (e.g., "7d ago", "2mo ago") and other platforms
3. **DISCARD any result older than 7 days from today** — do NOT include it in the report, do NOT quote it, do NOT use it for sentiment classification
4. If most results are older than 7 days, say so honestly: "Limited discussion found in the last 7 days"
5. NEVER silently widen the window — if the 7-day window is thin, report that it's thin
6. In the final report, every source MUST have its date stated. Any source without a verifiable date within the last 7 days gets excluded.

### Step 1.5 — Resolve X/Twitter handle (MANDATORY before any searches)

**⛔ Do NOT guess the X handle. Do NOT skip this step.**

Run a single search to find the brand's verified X handle:

```bash
tinyfish search query "{brand} site:x.com"
```

Look at the profile URLs that come back (e.g., `x.com/Tiny_Fish`, `x.com/sudheenair`). Extract the **primary brand handle** — this is the one you'll use in all X queries below. Also note any key people handles (CEO, founders) for additional queries.

**Store the result:** `VERIFIED_HANDLE={handle}` — use this variable mentally for all X queries. If no profile URL comes back, note that X coverage will be limited.

### Step 2 — Run multi-angle searches

Run **parallel searches** across different angles. For most platforms, include date strings (e.g., `{current month year}`) to help narrow results. **⛔ EXCEPTION: X/Twitter queries MUST NOT include date strings** — tweets don't contain "2026" or "May 2026" in their text, so adding date strings causes the search engine to filter out real tweets before they reach you. Use snowflake decoding to date-gate X results AFTER they come back. This is the #1 cause of missing X coverage — the agent adds year/month to every query, search engines match on page text, and tweets silently disappear from results.

#### 2a — X/Twitter searches (MANDATORY — all 3 patterns REQUIRED)

**⛔ This is a separate mandatory block, not optional. All 3 query patterns below MUST run. The agent has historically skipped these and missed 80%+ of X activity as a result.**

Generic `site:x.com "{brand}"` queries return mostly **profile page URLs** (undateable, useless). The following 3 patterns are specifically designed to return individual tweet URLs with `/status/` IDs that can be snowflake-decoded:

```bash
# PATTERN 1: Brand's own tweets (returns /status/ URLs)
# ⛔ NO date strings — tweets don't contain "2026" in text. Snowflake-decode dates after.
tinyfish search query "x.com/{VERIFIED_HANDLE}/status"
tinyfish search query "site:x.com/{VERIFIED_HANDLE}/status"

# PATTERN 2: Anyone tagging the brand (returns /status/ URLs from other users)
tinyfish search query "\"@{VERIFIED_HANDLE}\" site:x.com"
tinyfish search query "@{VERIFIED_HANDLE} site:x.com"

# PATTERN 3: Organic mentions by name without tagging (people discussing the brand in tweet text)
tinyfish search query "site:x.com \"{brand}\""
tinyfish search query "site:x.com \"{brand}.ai\""

# PATTERN 4: Product-specific keywords (mine earlier snippets for these)
tinyfish search query "site:x.com {brand} {product_keyword}"
```

**Verification gate:** After running all 3 patterns, count how many unique `/status/` URLs you got. If fewer than 5, run additional queries using product-specific keywords found in the brand's recent announcements or from earlier search snippets (e.g., product names, feature launches, event names). Profile-page snippets from generic searches often contain recent tweet text — mine those for keywords to construct targeted follow-up queries.

Also run queries for any key people handles identified in Step 1.5:
```bash
# ⛔ NO date strings for X — same rule applies to people handles
tinyfish search query "x.com/{person_handle}/status {brand}"
tinyfish search query "site:x.com/{person_handle}/status"
```

#### 2b — All other platform searches

```bash
# Direct brand mentions (last 7 days)
tinyfish search query "{brand} {YYYY-MM-DD range, e.g. 'May 2026'}"

# Reddit / forum discussions
tinyfish search query "site:reddit.com {brand} {current month year}"

# Hacker News discussions
tinyfish search query "site:news.ycombinator.com {brand} {current month year}"

# News coverage
tinyfish search query "{brand} news {current month year}"

# Developer community
tinyfish search query "{brand} developer API feedback {current month year}"

# Negative sentiment
tinyfish search query "{brand} problems issues complaints {current month year}"

# Positive sentiment
tinyfish search query "{brand} love amazing best {current month year}"

# LinkedIn
tinyfish search query "site:linkedin.com {brand} {current month year}"

# YouTube
tinyfish search query "site:youtube.com {brand} {current month year}"
```

Replace `{brand}` with the user's target and use the current month/year for date context.

Adapt queries to the domain:
- **B2B SaaS**: add "pricing", "migration", "enterprise", "support experience"
- **Consumer**: add "worth it", "alternatives", "honest review"
- **Open source**: add "site:github.com", "contributing", "maintainer"
- **Personal brand**: add "talk", "keynote", "interview", "thread"

Run at least 4 search queries. Run up to 10 for comprehensive briefs.

**⚡ EFFICIENCY: Run ALL searches + date gating + date verification in ONE `execute_code` block.** Use `from hermes_tools import terminal` to call TinyFish search from Python, then immediately dedup, date-gate, and verify YouTube dates (via curl) in the same block. Do NOT spread searches across multiple tool calls — the user sees each call as latency. One block, one wait. **Use `scripts/social_listening_sweep.py` as the template** — it handles all search queries, dedup, relevance filtering, X snowflake decoding, LinkedIn prefix heuristic, YouTube curl date-check, and Reddit snippet dates in a single block. Copy it, edit the CONFIG section, and run.

### Step 3 — DATE GATE ON SEARCH RESULTS (mandatory BEFORE any fetching)

**⛔ HARD STOP. Do NOT fetch ANY URLs until this gate is passed.**

**THIS IS THE