@botlearn/twitter-intel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BotLearn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @botlearn/twitter-intel
+
+> Twitter/X platform intelligence gathering — tracking KOLs, extracting trending topics, analyzing engagement signals, detecting bot activity, and synthesizing actionable insights for OpenClaw Agent
+
+## Installation
+
+```bash
+# via npm
+npm install @botlearn/twitter-intel
+
+# via clawhub
+clawhub install @botlearn/twitter-intel
+```
+
+## Category
+
+Information Retrieval
+
+## Dependencies
+
+None
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `manifest.json` | Skill metadata and configuration |
+| `skill.md` | Role definition and activation rules |
+| `knowledge/` | Domain knowledge documents |
+| `strategies/` | Behavioral strategy definitions |
+| `tests/` | Smoke and benchmark tests |
+
+## License
+
+MIT

package/knowledge/anti-patterns.md

@@ -0,0 +1,86 @@
+---
+domain: twitter-intel
+topic: anti-patterns
+priority: medium
+ttl: 30d
+---
+
+# Twitter Intelligence — Anti-Patterns
+
+## Engagement Blindness Anti-Patterns
+
+### 1. Equating Virality with Credibility
+- **Problem**: Treating a tweet with 50K retweets as inherently more credible than one with 500 retweets
+- **Why it fails**: Virality is driven by emotional resonance, controversy, and algorithmic amplification — not accuracy. Misinformation routinely outperforms corrections in engagement metrics
+- **Fix**: Always evaluate the source account's credibility score independently of engagement numbers. A Nano-KOL with domain expertise and 200 likes may carry more intelligence value than a Mega-KOL hot take with 100K likes
+
+### 2. Like Count as Sentiment Proxy
+- **Problem**: Interpreting high like counts as public agreement or approval
+- **Why it fails**: Users like tweets for many reasons: humor, relatability, bookmarking, ironic appreciation. Likes on sarcastic or critical tweets are easily misread as endorsement of the surface message
+- **Fix**: Use explicit textual sentiment analysis on the tweet content itself. Treat likes as an attention signal, not an opinion signal. Cross-reference with reply sentiment for ground truth
+
+### 3. Follower Count as Authority Measure
+- **Problem**: Automatically ranking accounts with more followers as more authoritative
+- **Why it fails**: Follower counts can be inflated through purchasing, follow-back schemes, or historical virality unrelated to current domain expertise. Many genuine domain experts have modest followings
+- **Fix**: Use the composite credibility score from knowledge/best-practices.md, which weights listed count, original content ratio, and engagement quality alongside follower count
+
+### 4. Impression Count Overreliance
+- **Problem**: Treating impression counts as a reliable measure of message reach and impact
+- **Why it fails**: Impressions measure timeline appearances, not actual reading. Auto-scrolling, algorithmic insertion, and muted accounts all inflate impressions without genuine attention
+- **Fix**: Use engagement rate (interactions / impressions) as the meaningful metric. Low engagement rate on high impressions suggests passive exposure, not active reception
+
+## Sarcasm & Tone Anti-Patterns
+
+### 5. Ignoring Sarcasm and Irony Markers
+- **Problem**: Taking tweet text at face value without assessing tone, leading to inverted sentiment classification
+- **Why it fails**: Twitter culture is heavily sarcastic. Tweets like "Oh great, another data breach, exactly what we needed" would be classified as positive without tone analysis
+- **Fix**: Check for sarcasm indicators:
+  - Quotation marks around praise ("great" move)
+  - Hyperbolic positive language in negative contexts
+  - Eye-roll or clown emojis following a statement
+  - "Surely" / "definitely" / "totally" in contexts that suggest the opposite
+  - Thread context: sarcastic reply to a serious tweet
+  - Account history: does this user typically use irony?
+
+### 6. Context-Free Quote Tweet Analysis
+- **Problem**: Analyzing the quoted tweet's text without considering the quoting user's commentary
+- **Why it fails**: Quote tweets are frequently used to disagree, mock, or add critical commentary. The quoted content and the quoting commentary often have opposite sentiments
+- **Fix**: Always analyze the quote tweet as a composite: original text + quoting commentary + any added media. The quoting user's intent is the primary signal, not the original content
+
+### 7. Thread Fragment Extraction
+- **Problem**: Extracting a single tweet from a multi-tweet thread and analyzing it in isolation
+- **Why it fails**: Thread authors build nuanced arguments across tweets. A single tweet may contain a devil's advocate position, a setup for a counterpoint, or a hypothetical — all of which are misrepresented when isolated
+- **Fix**: Always retrieve and analyze the complete thread (using `conversation_id`). Attribute the overall thread thesis, not individual tweet fragments
+
+## Bot Amplification Anti-Patterns
+
+### 8. Treating All Engagement as Organic
+- **Problem**: Including bot-generated retweets, likes, and replies in engagement metrics and trend calculations without filtering
+- **Why it fails**: Bot networks can manufacture artificial trends, inflate engagement by 10-100x, and create a false impression of consensus. Reporting bot-amplified metrics as organic misleads intelligence consumers
+- **Fix**: Run bot detection heuristics (knowledge/domain.md) on the engagement sources before reporting metrics. Report both raw and bot-filtered engagement numbers. Flag topics where >15% of engagement comes from suspected bots
+
+### 9. Coordinated Hashtag Campaigns as Organic Trends
+- **Problem**: Reporting a trending hashtag as an organic trend when it is being driven by a coordinated campaign
+- **Why it fails**: Organized groups (political campaigns, marketing agencies, state actors) routinely coordinate hashtag pushes. The hashtag may trend without genuine organic interest
+- **Fix**: Check for coordination signals:
+  - Multiple accounts tweeting the same hashtag within the same 5-minute window with similar/identical text
+  - Accounts in the campaign share creation dates, follower patterns, or bio templates
+  - Hashtag volume drops sharply after the campaign window — organic trends have longer tails
+  - Compare the hashtag's geographic spread — coordinated campaigns often originate from a single region
+
+### 10. Astroturfing Misread as Grassroots Movement
+- **Problem**: Presenting an astroturfing campaign (organized fake grassroots activity) as genuine public sentiment
+- **Why it fails**: Sophisticated astroturfing uses aged accounts, varied content, and staggered timing to mimic organic activity. Without careful analysis, it passes initial filters
+- **Fix**: Apply the KOL Cascade Analysis from knowledge/best-practices.md. Genuine grassroots movements show Micro-KOL-to-Macro-KOL cascade over days. Astroturfing shows simultaneous activation across account tiers with no prior Micro-KOL buildup
+
+## Analysis & Reporting Anti-Patterns
+
+### 11. Recency Bias in Trend Assessment
+- **Problem**: Reporting the most recent tweets as the definitive position on a topic without historical baseline
+- **Why it fails**: Twitter discourse oscillates rapidly. A negative reaction in the last 2 hours may follow days of positive sentiment, or vice versa. Snapshot analysis misrepresents the trajectory
+- **Fix**: Always establish a baseline period (7-30 days) before assessing current sentiment. Report both the current state and the direction of change. Use the Sentiment Shift Detection technique from knowledge/best-practices.md
+
+### 12. Single-Platform Echo Chamber
+- **Problem**: Treating Twitter as representative of broader public opinion
+- **Why it fails**: Twitter's user base skews toward specific demographics (urban, media-engaged, tech-savvy). Topics that dominate Twitter may be irrelevant to the broader population, and vice versa. Twitter's algorithmic amplification creates feedback loops
+- **Fix**: Always caveat intelligence with "on Twitter/X" — never extrapolate to general public sentiment. Recommend cross-platform validation when the user needs broader opinion data. Note the platform's demographic skew in the confidence assessment

package/knowledge/best-practices.md

@@ -0,0 +1,117 @@
+---
+domain: twitter-intel
+topic: signal-filtering-credibility-trend-detection
+priority: high
+ttl: 30d
+---
+
+# Twitter Intelligence — Best Practices
+
+## Signal Filtering Methodology
+
+### 1. Multi-Layer Noise Reduction
+Apply filters sequentially to reduce the tweet corpus to actionable signals:
+1. **Language filter** — Restrict to target language(s) using `lang:` operator
+2. **Bot filter** — Exclude accounts matching bot heuristics from knowledge/domain.md
+3. **Retweet deduplication** — Collapse retweet chains to original tweet; count retweets as amplification metric
+4. **Relevance filter** — Score tweet-to-topic semantic similarity; discard below 0.6 threshold
+5. **Authority filter** — Weight remaining tweets by source KOL tier (from knowledge/domain.md)
+
+### 2. Signal-to-Noise Ratio Optimization
+- Prefer `-is:retweet` for opinion extraction — retweets indicate amplification, not original thought
+- Use `is:quote` to capture annotated discourse — quote tweets reveal disagreement, nuance, and counter-narratives
+- Filter for `has:links` when seeking evidence-backed claims
+- Apply `min_faves:` thresholds proportional to the topic's tweet volume:
+  - High-volume topic (>10K tweets/day): `min_faves:50`
+  - Medium-volume topic (1K-10K/day): `min_faves:10`
+  - Low-volume/niche topic (<1K/day): no minimum — all signals matter
+
+### 3. Temporal Window Selection
+- **Breaking news**: Last 1-4 hours — prioritize recency over engagement
+- **Trend monitoring**: Last 24-72 hours — balance recency with engagement signals
+- **Sentiment baseline**: Last 7-30 days — establish norms before measuring shifts
+- **Historical analysis**: Full archive — requires Academic/Pro API access
+
+## Credibility Assessment Framework
+
+### Account Credibility Score (0-100)
+
+Calculate a composite credibility score for each account:
+
+| Factor | Weight | Scoring |
+|--------|--------|---------|
+| Account age | 15% | <30 days: 0, 30d-1y: 40, 1-3y: 70, 3y+: 100 |
+| Follower/following ratio | 15% | <0.5: 20, 0.5-2: 40, 2-10: 70, 10+: 100 |
+| Listed count per 1K followers | 15% | <1: 20, 1-5: 50, 5-20: 80, 20+: 100 |
+| Original content ratio | 15% | <20%: 20, 20-50%: 50, 50-80%: 80, 80%+: 100 |
+| Verified status | 10% | None: 40, Blue: 60, Gold/Grey: 100 |
+| Bio completeness | 10% | Empty: 0, Generic: 30, Professional with affiliations: 100 |
+| Engagement quality | 10% | Bot-like patterns: 0, Normal: 60, High-quality replies: 100 |
+| Posting consistency | 10% | Sporadic/burst: 30, Regular cadence: 70, Daily with variety: 100 |
+
+### Credibility Tiers
+
+| Tier | Score | Treatment |
+|------|-------|-----------|
+| Authoritative | 80-100 | Primary source — cite directly, high confidence |
+| Credible | 60-79 | Reliable source — cite with standard attribution |
+| Provisional | 40-59 | Use with caution — require corroboration from higher tier |
+| Suspect | 20-39 | Do not cite alone — only as supporting data with corroboration |
+| Unreliable | 0-19 | Exclude from analysis — flag if part of coordinated campaign |
+
+### Cross-Referencing Protocol
+- **Single-source claim**: Never report. Require 2+ independent Credible-tier sources
+- **Controversial claim**: Require 3+ independent sources across different KOL tiers
+- **Statistical claim**: Require primary data source or link to verifiable dataset
+- **Breaking event**: Allow single Authoritative-tier source with "unconfirmed" label; upgrade after corroboration
+
+## Trend Detection Techniques
+
+### 1. Volume Velocity Analysis
+Track tweet volume over sliding windows to detect acceleration:
+- Calculate **tweets per hour** for the target topic over the last 72 hours
+- Compute **velocity** = (current hour volume) / (average hourly volume over past 72h)
+- Thresholds:
+  - Velocity 1.5-3x: **Elevated interest** — monitor closely
+  - Velocity 3-10x: **Emerging trend** — begin analysis
+  - Velocity >10x: **Viral event** — prioritize for immediate briefing
+
+### 2. Hashtag Co-occurrence Mapping
+- Track which hashtags appear together in tweets about the target topic
+- New co-occurrences signal narrative evolution (e.g., a tech topic suddenly co-occurring with #regulation)
+- Build a co-occurrence graph; detect new clusters forming over 24-48h windows
+
+### 3. KOL Cascade Analysis
+- Track when a topic moves across KOL tiers:
+  - Nano/Micro-KOL discussion first → Macro-KOL pickup → Mega-KOL amplification = organic trend
+  - Mega-KOL first → immediate broad amplification without prior Micro-KOL discussion = top-down narrative push
+- The **cascade direction** indicates whether a trend is grassroots or manufactured
+
+### 4. Sentiment Shift Detection
+- Establish a rolling 7-day sentiment baseline for the target topic
+- Detect statistically significant shifts (>2 standard deviations from baseline)
+- Categorize shifts:
+  - **Gradual drift**: Sentiment changes over days — underlying narrative evolution
+  - **Sharp reversal**: Sentiment flips within hours — triggered by a specific event or revelation
+  - **Polarization spike**: Average sentiment stays similar but variance increases — growing disagreement
+
+### 5. Geographic & Demographic Spread
+- Track when a topic crosses from one geographic region or language community to another
+- Use `place_country:` and `lang:` operators to segment
+- Cross-community spread is a strong indicator of a trend gaining mainstream traction
+
+## Intelligence Report Structure
+
+### Standard Briefing Format
+1. **Executive Summary** — 2-3 sentence overview: what happened, why it matters, confidence level
+2. **Key Findings** — Bulleted list of 3-5 main intelligence points, each with source attribution
+3. **KOL Positions** — Table of notable KOL statements with credibility tier and reach metrics
+4. **Trend Metrics** — Volume, velocity, sentiment data with time-series context
+5. **Bot/Inauthenticity Assessment** — Percentage of engagement flagged as inauthentic; impact on findings
+6. **Confidence Rating** — Overall confidence: High (80-100%), Medium (50-79%), Low (<50%) with justification
+7. **Recommended Actions** — What the user should do with this intelligence; monitoring suggestions
+
+### Confidence Rating Criteria
+- **High (80-100%)**: 3+ Authoritative sources, consistent across KOL tiers, minimal bot contamination (<5%)
+- **Medium (50-79%)**: 2+ Credible sources, mostly consistent with minor discrepancies, moderate bot presence (5-15%)
+- **Low (<50%)**: Single source or conflicting accounts, high bot contamination (>15%), or rapidly evolving situation

package/knowledge/domain.md

@@ -0,0 +1,140 @@
+---
+domain: twitter-intel
+topic: twitter-api-engagement-metrics-kol-signals
+priority: high
+ttl: 30d
+---
+
+# Twitter Intelligence — API, Engagement Metrics & KOL Signals
+
+## Twitter/X API v2 Endpoints
+
+### Tweet Search
+- **Recent Search** — `GET /2/tweets/search/recent` — Tweets from last 7 days
+  - Query operators: `from:`, `to:`, `is:retweet`, `is:reply`, `is:quote`, `has:media`, `has:links`, `lang:`
+  - Max results per request: 100 (paginate with `next_token`)
+  - Rate limit: 450 requests / 15-min window (App-level), 180 (User-level)
+- **Full-Archive Search** — `GET /2/tweets/search/all` — Complete tweet history (Academic/Pro access)
+  - Same query operators as Recent Search
+  - Rate limit: 300 requests / 15-min window
+- **Filtered Stream** — `POST /2/tweets/search/stream/rules` + `GET /2/tweets/search/stream`
+  - Real-time streaming with up to 25 concurrent rules (Basic), 1000 (Pro)
+  - Supports all search operators as filter rules
+
+### User & Account Data
+- **User Lookup** — `GET /2/users/by/username/:username`
+  - Fields: `id`, `name`, `username`, `created_at`, `description`, `public_metrics`, `verified`, `verified_type`
+- **User Tweets Timeline** — `GET /2/users/:id/tweets` — Up to 3,200 most recent tweets
+- **Followers/Following** — `GET /2/users/:id/followers`, `GET /2/users/:id/following`
+  - Rate limit: 15 requests / 15-min window
+
+### Engagement & Metrics
+- **Tweet Metrics** (via `tweet.fields=public_metrics`):
+  - `retweet_count`, `reply_count`, `like_count`, `quote_count`, `bookmark_count`, `impression_count`
+- **User Metrics** (via `user.fields=public_metrics`):
+  - `followers_count`, `following_count`, `tweet_count`, `listed_count`
+
+### Trend Data
+- **Trending Topics** — `GET /1.1/trends/place.json?id={WOEID}`
+  - Returns top 50 trends for a location (WOEID-based)
+  - Includes `tweet_volume` (last 24h) when available
+  - Rate limit: 75 requests / 15-min window
+
+## Search Query Operators
+
+### Content Filters
+- `"exact phrase"` — Match exact phrase in tweet text
+- `keyword1 keyword2` — Both terms required (implicit AND)
+- `keyword1 OR keyword2` — Match either term
+- `-keyword` — Exclude tweets containing term
+- `#hashtag` — Match hashtag
+- `$TICKER` — Match cashtag (financial symbols)
+- `url:"domain.com"` — Tweets containing links to domain
+
+### Account Filters
+- `from:username` — Tweets authored by account
+- `to:username` — Tweets directed at account (replies/mentions)
+- `@username` — Tweets mentioning account
+- `retweets_of:username` — Retweets of account's tweets
+
+### Tweet Type Filters
+- `is:retweet` / `-is:retweet` — Include/exclude retweets
+- `is:reply` / `-is:reply` — Include/exclude replies
+- `is:quote` — Quote tweets only
+- `is:verified` — From verified accounts only
+- `has:media` — Tweets with images or video
+- `has:links` — Tweets with URLs
+- `has:hashtags` — Tweets with at least one hashtag
+
+### Temporal & Engagement Filters
+- `since:2024-01-01` / `until:2024-12-31` — Date range (YYYY-MM-DD)
+- `min_retweets:100` — Minimum retweet threshold
+- `min_faves:500` — Minimum like threshold
+- `min_replies:50` — Minimum reply threshold
+- `lang:en` — Language filter (ISO 639-1)
+
+## KOL Identification Signals
+
+### Authority Indicators
+| Signal | Description | Weight |
+|--------|------------|--------|
+| Verified badge | Blue checkmark (paid) or gold/grey (org/gov) | Medium — verification is now pay-to-play; gold/grey is stronger |
+| Follower-to-following ratio | High ratio (>10:1) suggests organic authority | High |
+| Listed count | Number of lists the account appears on — indicates curation by others | High |
+| Account age | Older accounts with consistent activity are more credible | Medium |
+| Bio & affiliations | Institutional affiliation, professional credentials | High |
+
+### Content Quality Indicators
+| Signal | Description | Weight |
+|--------|------------|--------|
+| Original tweet ratio | Proportion of original tweets vs retweets — high ratio suggests thought leadership | High |
+| Thread creation | Regularly publishes long-form threads — indicates deep analysis | Medium |
+| Citation behavior | Links to primary sources, papers, data — indicates research rigor | High |
+| Engagement quality | Reply-to-like ratio — high reply engagement suggests genuine discourse | Medium |
+| Consistency | Posts on-topic regularly over months/years — not a flash account | High |
+
+### KOL Classification Tiers
+
+| Tier | Followers | Characteristics | Intelligence Value |
+|------|-----------|----------------|-------------------|
+| Mega-KOL | 1M+ | Broad reach, high noise, opinion-shaping | Trend confirmation, narrative direction |
+| Macro-KOL | 100K-1M | Industry visibility, media crossover | Sector sentiment, emerging narratives |
+| Mid-KOL | 10K-100K | Domain specialists, practitioner voices | Technical signals, insider perspective |
+| Micro-KOL | 1K-10K | Niche experts, early adopters | Early signals, ground-truth validation |
+| Nano-KOL | <1K | Hyper-specialized, often undervalued | Deep domain knowledge, contrarian signals |
+
+## Engagement Metric Interpretation
+
+### Healthy Engagement Ratios
+- **Like-to-impression ratio**: 1-3% is typical; >5% indicates high resonance
+- **Retweet-to-like ratio**: 0.1-0.3 is normal; >0.5 suggests strong shareability or controversy
+- **Reply-to-like ratio**: 0.01-0.05 is normal; >0.1 indicates contentious content ("ratio'd")
+- **Quote-to-retweet ratio**: >0.3 suggests the tweet is being challenged or annotated
+
+### Anomalous Engagement Patterns
+- **Spike without context**: Sudden engagement surge with no clear catalyst — possible bot amplification
+- **Follower burst**: Account gains 10K+ followers in <24h without viral content — possible purchased followers
+- **Uniform engagement timing**: Likes/retweets arriving at metronomic intervals — bot signature
+- **Low-quality reply flood**: High reply count but replies are generic, single-emoji, or from low-follower accounts — astroturfing
+
+## Bot Detection Heuristics
+
+### Account-Level Signals
+- Default profile image or AI-generated avatar
+- Username contains long random number strings (e.g., `user83749201`)
+- Account created in bulk pattern (similar creation dates, sequential naming)
+- Bio is generic, copied, or empty; displays no domain expertise
+- Following/follower ratio near 1:1 with high absolute numbers (follow-back bot)
+
+### Behavior-Level Signals
+- Tweets at inhuman frequency (>100 tweets/hour)
+- Posts 24/7 with no sleep pattern
+- Content is entirely retweets or templated replies
+- Engages across unrelated topics with no coherent interest graph
+- Replies within seconds of target tweet publication
+
+### Network-Level Signals
+- Cluster of accounts retweeting the same content within minutes
+- Shared followers/following lists across multiple accounts
+- Coordinated hashtag usage at the same timestamps
+- Reply chains that form repetitive patterns (e.g., same phrase variations)

package/manifest.json

@@ -0,0 +1,26 @@
+{
+  "name": "@botlearn/twitter-intel",
+  "version": "0.1.0",
+  "description": "Twitter/X platform intelligence gathering — tracking KOLs, extracting trending topics, analyzing engagement signals, detecting bot activity, and synthesizing actionable insights for OpenClaw Agent",
+  "category": "information-retrieval",
+  "author": "BotLearn",
+  "benchmarkDimension": "information-retrieval",
+  "expectedImprovement": 30,
+  "dependencies": {},
+  "compatibility": {
+    "openclaw": ">=0.5.0"
+  },
+  "files": {
+    "skill": "skill.md",
+    "knowledge": [
+      "knowledge/domain.md",
+      "knowledge/best-practices.md",
+      "knowledge/anti-patterns.md"
+    ],
+    "strategies": [
+      "strategies/main.md"
+    ],
+    "smokeTest": "tests/smoke.json",
+    "benchmark": "tests/benchmark.json"
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@botlearn/twitter-intel",
+  "version": "0.1.0",
+  "description": "Twitter/X platform intelligence gathering — tracking KOLs, extracting trending topics, analyzing engagement signals, detecting bot activity, and synthesizing actionable insights for OpenClaw Agent",
+  "type": "module",
+  "main": "manifest.json",
+  "files": [
+    "manifest.json",
+    "skill.md",
+    "knowledge/",
+    "strategies/",
+    "tests/",
+    "README.md"
+  ],
+  "keywords": [
+    "botlearn",
+    "openclaw",
+    "skill",
+    "information-retrieval"
+  ],
+  "author": "BotLearn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/readai-team/botlearn-awesome-skills.git",
+    "directory": "packages/skills/twitter-intel"
+  },
+  "homepage": "https://github.com/readai-team/botlearn-awesome-skills/tree/main/packages/skills/twitter-intel",
+  "bugs": {
+    "url": "https://github.com/readai-team/botlearn-awesome-skills/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill.md

@@ -0,0 +1,48 @@
+---
+name: twitter-intel
+role: Twitter Intelligence Analyst
+version: 1.0.0
+triggers:
+  - "twitter"
+  - "tweet"
+  - "KOL"
+  - "trending"
+  - "X platform"
+  - "twitter intelligence"
+  - "twitter analysis"
+  - "influencer tracking"
+  - "twitter trends"
+  - "social listening"
+---
+
+# Role
+
+You are a Twitter Intelligence Analyst. When activated, you monitor the Twitter/X platform to track key opinion leaders (KOLs), extract trending narratives, analyze engagement signals, detect bot-driven amplification, and synthesize actionable intelligence reports from the platform's real-time discourse.
+
+# Capabilities
+
+1. Curate and maintain watchlists of KOLs, domain experts, and emerging voices within specified topics or industries
+2. Filter high-signal tweets from noise using engagement metrics, account credibility scoring, and content relevance analysis
+3. Extract and classify opinions, stances, and sentiment from tweet threads, quote tweets, and reply chains
+4. Detect emerging trends, narrative shifts, and coordinated amplification campaigns before they reach mainstream awareness
+5. Synthesize multi-source Twitter intelligence into structured, time-stamped briefings with confidence ratings and source attribution
+6. Identify bot networks, astroturfing patterns, and inauthentic engagement to separate organic signal from manufactured consensus
+
+# Constraints
+
+1. Never treat high engagement (likes, retweets) as a proxy for credibility — always verify the source account's authenticity and authority
+2. Never report on a trend based on a single tweet or a single account — require corroboration from 3+ independent sources
+3. Never ignore sarcasm, irony, or satire markers — always assess tweet tone before extracting sentiment or opinion
+4. Never present bot-amplified content as organic public opinion — always flag suspected inauthentic activity
+5. Always include temporal context (timestamps, trend velocity) — Twitter intelligence is time-sensitive by nature
+6. Always respect rate limits and platform terms of service when interfacing with Twitter/X API endpoints
+
+# Activation
+
+WHEN the user requests Twitter monitoring, KOL tracking, or trend analysis:
+1. Identify the target topic, industry, or set of accounts to monitor
+2. Execute source curation and signal filtering following strategies/main.md
+3. Apply knowledge/domain.md for API usage, metric interpretation, and KOL identification
+4. Evaluate findings using knowledge/best-practices.md for credibility and trend validation
+5. Check against knowledge/anti-patterns.md to avoid engagement blindness, sarcasm misreads, and bot amplification traps
+6. Output a structured intelligence briefing with confidence levels, source attribution, and temporal context

package/strategies/main.md

@@ -0,0 +1,113 @@
+---
+strategy: twitter-intel
+version: 1.0.0
+steps: 6
+---
+
+# Twitter Intelligence Strategy
+
+## Step 1: Source Curation
+- Parse the user's request to identify: **target topic**, **accounts of interest**, **time window**, **geographic scope**, and **desired intelligence type** (trend analysis, KOL tracking, sentiment monitoring, or event coverage)
+- IF the request is vague THEN ask one clarifying question to narrow the scope (e.g., "Which industry vertical?" or "Any specific accounts to prioritize?")
+- Build initial source lists:
+  - **Topic keywords**: Extract 3-7 primary keywords and hashtags relevant to the topic
+  - **KOL watchlist**: Identify 5-15 accounts across KOL tiers (from knowledge/domain.md) that are relevant to the topic
+  - **Exclusion list**: Identify known bot accounts, spam hashtags, and noise sources to exclude
+- Construct Twitter/X API search queries using operators from knowledge/domain.md:
+  - Primary query: topic keywords + `-is:retweet` + `lang:` filter
+  - KOL query: `from:` operators for watchlist accounts + topic keywords
+  - Trend query: hashtag co-occurrences + `min_faves:` threshold
+- Set the temporal window based on intelligence type:
+  - Breaking event: last 1-4 hours
+  - Trend monitoring: last 24-72 hours
+  - Baseline establishment: last 7-30 days
+
+## Step 2: Signal Filtering
+- Execute queries and collect raw tweet corpus
+- Apply multi-layer noise reduction from knowledge/best-practices.md:
+  1. Remove exact duplicates and retweet chains — collapse to original tweets with amplification counts
+  2. Run bot detection heuristics from knowledge/domain.md on all accounts in the corpus
+  3. Score each account using the Account Credibility Score framework (knowledge/best-practices.md)
+  4. Filter tweets by semantic relevance to the target topic — discard below 0.6 similarity threshold
+  5. Apply engagement thresholds proportional to topic volume
+- Tag each remaining tweet with metadata:
+  - Source credibility tier (Authoritative / Credible / Provisional / Suspect)
+  - Bot probability score (0-100%)
+  - Relevance score (0.6-1.0)
+- IF >15% of engagement is flagged as bot-driven THEN flag the topic for inauthenticity risk
+- VERIFY against anti-pattern #8 (knowledge/anti-patterns.md): ensure bot engagement is separated from organic metrics
+
+## Step 3: Opinion Extraction
+- For each high-signal tweet (credibility tier >= Provisional, relevance >= 0.7):
+  - Extract the **stated position** — what claim or opinion does the tweet express?
+  - Classify **sentiment** — positive / negative / neutral / mixed toward the target topic
+  - Detect **tone markers** — check for sarcasm, irony, or satire per anti-pattern #5 (knowledge/anti-patterns.md)
+  - IF the tweet is a quote tweet THEN analyze as composite (original + commentary) per anti-pattern #6
+  - IF the tweet is part of a thread THEN retrieve full thread via `conversation_id` and analyze holistically per anti-pattern #7
+- Group extracted opinions into **stance clusters**:
+  - Supporters (positive sentiment toward topic/entity)
+  - Critics (negative sentiment toward topic/entity)
+  - Neutral analysts (factual commentary without clear stance)
+  - Contrarians (minority positions that diverge from the dominant narrative)
+- For each cluster, identify the **strongest voice** — the highest-credibility KOL representing that position
+- Calculate **opinion distribution** — percentage of credible voices in each cluster
+
+## Step 4: Trend Detection
+- Apply Volume Velocity Analysis from knowledge/best-practices.md:
+  - Calculate tweets per hour over the analysis window
+  - Compute velocity relative to 72-hour average
+  - IF velocity > 3x THEN classify as emerging trend
+  - IF velocity > 10x THEN classify as viral event — prioritize for immediate briefing
+- Execute Hashtag Co-occurrence Mapping:
+  - Build co-occurrence graph for hashtags in the filtered corpus
+  - Identify new hashtag clusters forming in the last 24-48 hours
+  - Flag unexpected co-occurrences (e.g., tech topic + political hashtag = narrative hijacking risk)
+- Perform KOL Cascade Analysis:
+  - Track the chronological spread across KOL tiers
+  - IF Micro-KOL → Macro-KOL → Mega-KOL cascade THEN classify as organic trend
+  - IF Mega-KOL-first or simultaneous cross-tier activation THEN flag as top-down narrative push per anti-pattern #9
+- Run Sentiment Shift Detection:
+  - Compare current sentiment against the 7-day rolling baseline
+  - IF shift > 2 standard deviations THEN classify the shift type (gradual drift, sharp reversal, or polarization spike)
+- VERIFY against anti-pattern #10: check for astroturfing signatures in any detected trends
+
+## Step 5: Insight Synthesis
+- Merge findings from Steps 2-4 into a coherent intelligence picture:
+  - Connect opinion clusters (Step 3) with trend dynamics (Step 4)
+  - Identify **causal narratives**: what events or statements triggered the observed patterns?
+  - Assess **trajectory**: is the trend accelerating, plateauing, or declining?
+  - Evaluate **cross-topic spillover**: is the topic affecting or being affected by adjacent conversations?
+- Generate confidence ratings using criteria from knowledge/best-practices.md:
+  - Count corroborating sources across credibility tiers
+  - Calculate bot contamination percentage
+  - Assess source diversity (single echo chamber vs. multi-community signal)
+- Identify **intelligence gaps** — what questions remain unanswered? What data would increase confidence?
+- VERIFY against anti-pattern #11: ensure the assessment includes baseline context, not just the latest snapshot
+- VERIFY against anti-pattern #12: caveat all findings as Twitter/X-specific; do not extrapolate to general public opinion
+
+## Step 6: Intelligence Briefing Output
+- Structure the output following the Standard Briefing Format from knowledge/best-practices.md:
+  1. **Executive Summary** — 2-3 sentences: what the intelligence reveals, why it matters, confidence level
+  2. **Key Findings** — 3-5 bulleted intelligence points, each with:
+     - The finding itself
+     - Source attribution (KOL name, credibility tier, tweet link)
+     - Corroboration count (how many independent sources support this)
+  3. **KOL Positions** — Table of notable KOL statements:
+     - Account handle | Credibility tier | Follower count | Position summary | Tweet link
+  4. **Trend Metrics** — Quantitative data:
+     - Tweet volume and velocity (with time-series if available)
+     - Sentiment distribution (% positive / negative / neutral)
+     - Top hashtags and co-occurrences
+     - Geographic spread (if detectable)
+  5. **Bot & Inauthenticity Assessment** — Percentage of flagged engagement; impact on findings
+  6. **Confidence Rating** — High / Medium / Low with explicit justification
+  7. **Recommended Actions** — What the user should do next:
+     - Accounts to watch for follow-up developments
+     - Suggested monitoring frequency
+     - Cross-platform validation recommendations if confidence is Medium or Low
+- SELF-CHECK before delivery:
+  - Are all claims backed by attributed sources?
+  - Have bot-contaminated metrics been flagged?
+  - Is temporal context (timestamps, trend direction) included throughout?
+  - Does the briefing avoid the 12 anti-patterns from knowledge/anti-patterns.md?
+  - IF any check fails THEN loop back to the relevant step and re-analyze

package/tests/benchmark.json

@@ -0,0 +1,476 @@
+{
+  "version": "0.0.1",
+  "dimension": "information-retrieval",
+  "tasks": [
+    {
+      "id": "bench-easy-01",
+      "difficulty": "easy",
+      "description": "Identify top KOLs for a well-known topic",
+      "input": "List the top 5 most influential accounts on Twitter/X discussing artificial intelligence. For each account, provide their handle, follower count, KOL tier, and a brief description of why they are influential in the AI space.",
+      "rubric": [
+        {
+          "criterion": "KOL Identification Accuracy",
+          "weight": 0.4,
+          "scoring": {
+            "5": "Identifies 5 genuinely influential AI accounts across multiple tiers (researchers, industry leaders, commentators); accounts are widely recognized in the AI community",
+            "3": "Identifies 3-4 relevant accounts but selection is skewed toward one category (e.g., all corporate accounts)",
+            "1": "Identifies 1-2 relevant accounts mixed with irrelevant ones",
+            "0": "No relevant AI KOLs identified"
+          }
+        },
+        {
+          "criterion": "Metadata Completeness",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Each account includes: handle, follower count, KOL tier classification, credibility indicators, and a specific reason for their influence",
+            "3": "Handles and follower counts provided but missing tier classification or influence rationale",
+            "1": "Only handles listed without supporting data",
+            "0": "No metadata provided"
+          }
+        },
+        {
+          "criterion": "Source Diversity",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Accounts span multiple KOL tiers (Mega, Macro, Mid) and roles (researcher, founder, journalist, practitioner)",
+            "3": "Accounts from 2 tiers or roles",
+            "1": "All accounts from same tier or role",
+            "0": "No diversity consideration"
+          }
+        }
+      ],
+      "expectedScoreWithout": 35,
+      "expectedScoreWith": 75
+    },
+    {
+      "id": "bench-easy-02",
+      "difficulty": "easy",
+      "description": "Extract trending hashtags for a specific topic",
+      "input": "What are the top trending hashtags on Twitter/X related to cryptocurrency in the past 24 hours? Provide the hashtag, estimated tweet volume, and a one-sentence description of what each hashtag is about.",
+      "rubric": [
+        {
+          "criterion": "Hashtag Relevance",
+          "weight": 0.4,
+          "scoring": {
+            "5": "Returns 5+ genuinely trending crypto-related hashtags that are currently active; all are directly relevant to cryptocurrency topics",
+            "3": "Returns 3-4 relevant hashtags but includes 1-2 generic or outdated ones",
+            "1": "Returns mostly generic hashtags (#crypto, #bitcoin) without trending context",
+            "0": "Irrelevant hashtags"
+          }
+        },
+        {
+          "criterion": "Volume & Context Data",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Each hashtag includes estimated tweet volume, what it refers to, and why it is trending now",
+            "3": "Volume estimates provided but context is vague",
+            "1": "Hashtags listed without volume or context",
+            "0": "No supporting data"
+          }
+        },
+        {
+          "criterion": "Temporal Accuracy",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Hashtags are clearly from the last 24 hours with timestamps or recency indicators; distinguishes current trends from evergreen tags",
+            "3": "Some recency indication but not clearly time-bounded",
+            "1": "No temporal context — could be from any time period",
+            "0": "Returns outdated trends"
+          }
+        }
+      ],
+      "expectedScoreWithout": 35,
+      "expectedScoreWith": 80
+    },
+    {
+      "id": "bench-easy-03",
+      "difficulty": "easy",
+      "description": "Basic sentiment check on a public figure",
+      "input": "What is the general sentiment on Twitter/X toward Elon Musk this week? Provide a simple breakdown: percentage positive, negative, and neutral, with 2-3 example tweets for each category.",
+      "rubric": [
+        {
+          "criterion": "Sentiment Classification",
+          "weight": 0.4,
+          "scoring": {
+            "5": "Provides clear percentage breakdown with reasonable distribution; acknowledges mixed/polarized sentiment; methodology is explained",
+            "3": "Provides a general sentiment direction (mostly positive/negative) but percentages are vague or unsupported",
+            "1": "Single-word sentiment (e.g., 'negative') without nuance or data",
+            "0": "No sentiment analysis"
+          }
+        },
+        {
+          "criterion": "Example Quality",
+          "weight": 0.3,
+          "scoring": {
+            "5": "2-3 examples per category from credible accounts; examples clearly represent the stated sentiment; tone is correctly interpreted (sarcasm detected)",
+            "3": "1-2 examples per category but some are ambiguous or from low-credibility accounts",
+            "1": "Generic examples that do not clearly demonstrate the sentiment category",
+            "0": "No examples provided"
+          }
+        },
+        {
+          "criterion": "Temporal Framing",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Analysis is clearly bounded to the current week; notes any specific events driving sentiment shifts",
+            "3": "Roughly time-bounded but does not connect sentiment to specific events",
+            "1": "No clear time boundary; could be about any period",
+            "0": "Clearly outdated analysis"
+          }
+        }
+      ],
+      "expectedScoreWithout": 40,
+      "expectedScoreWith": 80
+    },
+    {
+      "id": "bench-med-01",
+      "difficulty": "medium",
+      "description": "Track narrative evolution around a policy event",
+      "input": "Analyze how the Twitter/X conversation around US data privacy legislation has evolved over the past month. Identify the key narrative phases, which KOLs drove each phase, and how sentiment shifted at each stage. Flag any coordinated campaign activity.",
+      "rubric": [
+        {
+          "criterion": "Narrative Phase Identification",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Identifies 3+ distinct narrative phases with clear temporal boundaries and triggering events; shows how the conversation evolved from one phase to the next",
+            "3": "Identifies 2 phases but boundaries are unclear or triggering events are not specified",
+            "1": "Treats the entire month as a single undifferentiated conversation",
+            "0": "No temporal analysis"
+          }
+        },
+        {
+          "criterion": "KOL Attribution",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Attributes specific KOLs to each narrative phase; shows cascade patterns (who spoke first, who amplified); credibility tiers assigned",
+            "3": "Names some KOLs but does not connect them to specific phases or show cascade dynamics",
+            "1": "Generic mention of 'influencers' without specific attribution",
+            "0": "No KOL analysis"
+          }
+        },
+        {
+          "criterion": "Sentiment Trajectory",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Maps sentiment across the full month with shifts clearly linked to events; distinguishes gradual drift from sharp reversals; reports baseline and deviations",
+            "3": "Reports overall sentiment change but without phase-by-phase granularity",
+            "1": "Single sentiment label for the whole period",
+            "0": "No sentiment analysis"
+          }
+        },
+        {
+          "criterion": "Coordination Detection",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Explicitly checks for coordinated campaigns; reports findings (whether coordination was detected or not) with evidence; distinguishes organic from manufactured activity",
+            "3": "Mentions coordination possibility but without systematic detection or evidence",
+            "1": "Does not address coordination at all",
+            "0": "Presents potentially coordinated activity as organic"
+          }
+        }
+      ],
+      "expectedScoreWithout": 25,
+      "expectedScoreWith": 65
+    },
+    {
+      "id": "bench-med-02",
+      "difficulty": "medium",
+      "description": "Competitive intelligence via Twitter KOL monitoring",
+      "input": "I'm launching a fintech startup focused on embedded payments. Monitor Twitter/X to identify: (1) the top 10 KOLs in the embedded finance space, (2) what they're saying about current market trends, and (3) any emerging competitors or partnerships being discussed. Provide a competitive intelligence briefing.",
+      "rubric": [
+        {
+          "criterion": "KOL Discovery",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Identifies 10 relevant KOLs across tiers (industry analysts, fintech founders, VC investors, developers); includes credibility scores and relevance justification for each",
+            "3": "Identifies 5-7 relevant KOLs but limited to one or two categories",
+            "1": "Identifies fewer than 5 KOLs or includes irrelevant accounts",
+            "0": "No KOL discovery"
+          }
+        },
+        {
+          "criterion": "Market Trend Extraction",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Extracts 3+ specific market trends with KOL source attribution; trends are actionable and relevant to embedded payments; includes supporting tweet evidence",
+            "3": "Identifies general fintech trends but not specific to embedded payments or lacking attribution",
+            "1": "Vague trend statements without evidence",
+            "0": "No trend analysis"
+          }
+        },
+        {
+          "criterion": "Competitive Signal Detection",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Identifies specific competitors or partnerships being discussed by KOLs; provides context on competitive positioning; flags early signals of market moves",
+            "3": "Mentions some competitors but without context or KOL attribution",
+            "1": "Generic competitive landscape without Twitter-specific intelligence",
+            "0": "No competitive signals"
+          }
+        },
+        {
+          "criterion": "Briefing Structure",
+          "weight": 0.15,
+          "scoring": {
+            "5": "Follows structured briefing format with executive summary, KOL table, trend analysis, competitive signals, and recommended monitoring actions",
+            "3": "Partially structured with some sections missing",
+            "1": "Unstructured narrative",
+            "0": "No organization"
+          }
+        }
+      ],
+      "expectedScoreWithout": 25,
+      "expectedScoreWith": 65
+    },
+    {
+      "id": "bench-med-03",
+      "difficulty": "medium",
+      "description": "Detect and analyze bot activity around a controversial topic",
+      "input": "Investigate whether bot networks are amplifying specific narratives about genetically modified organisms (GMOs) on Twitter/X. Identify suspected bot accounts, quantify their impact on the conversation's engagement metrics, and determine which narratives they are pushing. Separate organic KOL opinions from bot-amplified messaging.",
+      "rubric": [
+        {
+          "criterion": "Bot Detection Methodology",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Applies systematic bot detection using account-level, behavior-level, and network-level signals from domain knowledge; explains the heuristics used and their confidence",
+            "3": "Applies some bot detection but only at one level (e.g., account-level only) without network analysis",
+            "1": "Mentions bots but does not apply systematic detection",
+            "0": "No bot detection"
+          }
+        },
+        {
+          "criterion": "Impact Quantification",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Reports bot contamination percentage; provides both raw and bot-filtered engagement metrics; quantifies how much bot activity inflates specific narrative visibility",
+            "3": "Reports presence of bots but does not quantify their impact on metrics",
+            "1": "Vague mention of bot activity without quantification",
+            "0": "No quantification"
+          }
+        },
+        {
+          "criterion": "Narrative Separation",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Clearly separates organic KOL opinions from bot-amplified narratives; shows which narratives are genuinely held by credible voices vs. artificially boosted",
+            "3": "Identifies different narratives but does not clearly separate organic from amplified",
+            "1": "Treats all narratives equally without bot-organic distinction",
+            "0": "No narrative analysis"
+          }
+        },
+        {
+          "criterion": "Evidence Presentation",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Provides specific examples of suspected bot accounts with evidence (account age, posting patterns, network connections); shows coordination patterns",
+            "3": "Mentions suspected accounts but evidence is thin or anecdotal",
+            "1": "No specific examples or evidence",
+            "0": "Unsupported claims"
+          }
+        }
+      ],
+      "expectedScoreWithout": 20,
+      "expectedScoreWith": 60
+    },
+    {
+      "id": "bench-med-04",
+      "difficulty": "medium",
+      "description": "Multi-language Twitter intelligence gathering",
+      "input": "Monitor Twitter/X discourse about renewable energy policy in both English and Spanish-speaking communities. Compare the dominant narratives, key KOLs, and sentiment between the two language communities. Identify any cross-language narrative transfer.",
+      "rubric": [
+        {
+          "criterion": "Multi-Language Coverage",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Constructs separate queries for English and Spanish using lang: filters; identifies KOLs in both communities; provides analysis for each language independently",
+            "3": "Covers both languages but analysis is significantly deeper for one language",
+            "1": "Only covers one language effectively",
+            "0": "Single-language analysis despite multi-language request"
+          }
+        },
+        {
+          "criterion": "Cross-Community Comparison",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Provides structured comparison of narratives, KOLs, and sentiment between communities; identifies shared vs. unique concerns; notes cultural/political context differences",
+            "3": "Compares sentiment but does not compare narratives or KOLs in depth",
+            "1": "Presents each community separately without comparison",
+            "0": "No comparison"
+          }
+        },
+        {
+          "criterion": "Cross-Language Transfer Detection",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Identifies specific narratives or talking points that transferred from one language community to the other; traces the transfer timeline and amplifiers",
+            "3": "Notes some overlap between communities but does not trace transfer dynamics",
+            "1": "Does not address cross-language transfer",
+            "0": "Ignores the cross-language aspect entirely"
+          }
+        },
+        {
+          "criterion": "Output Quality",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Structured briefing with side-by-side comparison tables; confidence ratings for each community; recommended monitoring for both languages",
+            "3": "Readable output but lacks comparative structure",
+            "1": "Unstructured mixed narrative",
+            "0": "Disorganized output"
+          }
+        }
+      ],
+      "expectedScoreWithout": 20,
+      "expectedScoreWith": 60
+    },
+    {
+      "id": "bench-hard-01",
+      "difficulty": "hard",
+      "description": "Real-time crisis monitoring and misinformation detection",
+      "input": "A major cybersecurity breach has just been reported at a Fortune 500 company. Monitor Twitter/X in real-time to: (1) separate verified facts from speculation and misinformation, (2) identify which KOLs have credible insider knowledge vs. those amplifying rumors, (3) detect any coordinated disinformation campaigns attempting to manipulate the narrative, and (4) provide a real-time intelligence briefing that distinguishes confirmed facts from unverified claims with confidence levels.",
+      "rubric": [
+        {
+          "criterion": "Fact vs. Speculation Separation",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Explicitly categorizes each claim as confirmed/unconfirmed/speculation with evidence basis; traces claims to primary sources; flags contradictions between accounts; assigns per-claim confidence levels",
+            "3": "Separates some facts from speculation but categorization is inconsistent or missing evidence basis",
+            "1": "Presents all information with similar authority regardless of verification status",
+            "0": "No fact-checking or verification"
+          }
+        },
+        {
+          "criterion": "KOL Credibility Assessment",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Assesses each KOL's likely access to insider information based on professional background, prior accuracy, and institutional affiliation; distinguishes cybersecurity experts from general tech commentators; applies credibility scoring framework",
+            "3": "Identifies some credible sources but does not systematically assess expertise relevance",
+            "1": "Treats all KOLs equally regardless of domain expertise",
+            "0": "No credibility assessment"
+          }
+        },
+        {
+          "criterion": "Disinformation Detection",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Systematically checks for coordinated campaigns: synchronized posting, bot amplification, narrative manipulation; reports findings with specific evidence; quantifies disinformation contamination of the overall conversation",
+            "3": "Notes potential disinformation but without systematic detection or quantification",
+            "1": "Does not address disinformation possibility",
+            "0": "Presents disinformation as credible intelligence"
+          }
+        },
+        {
+          "criterion": "Real-Time Briefing Quality",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Structured briefing with clear timestamps, fact/speculation labels on each item, evolving confidence ratings, and recommended next monitoring actions; suitable for decision-makers",
+            "3": "Useful briefing but lacks timestamps or evolving confidence tracking",
+            "1": "Static summary without real-time structure",
+            "0": "Unusable output"
+          }
+        }
+      ],
+      "expectedScoreWithout": 15,
+      "expectedScoreWith": 55
+    },
+    {
+      "id": "bench-hard-02",
+      "difficulty": "hard",
+      "description": "Geopolitical narrative tracking across multiple stakeholder groups",
+      "input": "Track the Twitter/X discourse around US-China technology competition, specifically regarding semiconductor export controls. Map the conversation across four stakeholder groups: (1) US policy hawks, (2) industry/business voices, (3) Chinese state-affiliated accounts, and (4) neutral academic analysts. For each group, identify their narrative framing, key talking points, and how they engage with opposing narratives. Detect any state-sponsored information operations.",
+      "rubric": [
+        {
+          "criterion": "Stakeholder Group Mapping",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Successfully identifies and separates accounts into all 4 stakeholder groups with clear classification criteria; accounts are correctly attributed; includes 3+ KOLs per group",
+            "3": "Maps 2-3 groups but classification is imprecise or one group is missing",
+            "1": "Treats the conversation as monolithic without stakeholder segmentation",
+            "0": "No stakeholder mapping"
+          }
+        },
+        {
+          "criterion": "Narrative Framing Analysis",
+          "weight": 0.25,
+          "scoring": {
+            "5": "For each group: identifies the core narrative frame (e.g., national security vs. free trade vs. sovereign rights), key talking points, and rhetorical strategies; shows how frames differ and where they conflict",
+            "3": "Identifies general positions but does not analyze framing strategies or rhetorical differences",
+            "1": "Surface-level position summary without framing analysis",
+            "0": "No narrative analysis"
+          }
+        },
+        {
+          "criterion": "Cross-Group Engagement Analysis",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Maps how groups engage with each other: quote tweets, reply patterns, counter-narratives; identifies which groups are talking past each other vs. directly engaging; shows information flow between groups",
+            "3": "Notes some cross-group interaction but analysis is shallow",
+            "1": "Analyzes each group in isolation without cross-group dynamics",
+            "0": "No engagement analysis"
+          }
+        },
+        {
+          "criterion": "State-Sponsored Detection",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Applies systematic detection for state-affiliated accounts (official labels, behavior patterns, coordination signals); distinguishes organic vs. state-directed messaging; provides evidence for assessments; quantifies state-sponsored content share",
+            "3": "Identifies some state-affiliated accounts but detection is not systematic",
+            "1": "Mentions state involvement without evidence",
+            "0": "Ignores state-sponsored operations entirely"
+          }
+        }
+      ],
+      "expectedScoreWithout": 15,
+      "expectedScoreWith": 55
+    },
+    {
+      "id": "bench-hard-03",
+      "difficulty": "hard",
+      "description": "Predictive intelligence from early Twitter signals",
+      "input": "Based on current Twitter/X signals, identify 3 emerging technology trends that have not yet reached mainstream media coverage but are gaining traction among Micro-KOLs and Mid-KOLs in the tech space. For each trend, provide: the evidence trail (earliest tweets, KOL cascade progression), current velocity metrics, predicted timeline to mainstream awareness, and confidence level. Explain your methodology for distinguishing genuine early signals from noise.",
+      "rubric": [
+        {
+          "criterion": "Early Signal Detection",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Identifies 3 genuine emerging trends with clear evidence they originated in Micro/Mid-KOL circles; provides earliest tweet timestamps and shows the signal before mainstream pickup; trends are plausible and specific",
+            "3": "Identifies 2 trends but evidence trail is incomplete or one trend is already mainstream",
+            "1": "Identifies already-mainstream topics or vague trend categories",
+            "0": "No genuine early signal detection"
+          }
+        },
+        {
+          "criterion": "Evidence Quality & Cascade Analysis",
+          "weight": 0.25,
+          "scoring": {
+            "5": "For each trend: provides specific tweet evidence, shows KOL cascade progression with timestamps, maps the spread across KOL tiers; evidence is verifiable and attributed",
+            "3": "Some evidence provided but cascade analysis is incomplete or evidence is anecdotal",
+            "1": "Claims without supporting evidence or timeline",
+            "0": "No evidence"
+          }
+        },
+        {
+          "criterion": "Predictive Assessment",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Provides specific timeline predictions for mainstream awareness with justified reasoning; includes velocity metrics, comparisons to historical trend patterns, and explicit uncertainty bounds",
+            "3": "General timeline prediction without quantitative basis or uncertainty bounds",
+            "1": "No predictive element — only describes current state",
+            "0": "No prediction attempted"
+          }
+        },
+        {
+          "criterion": "Methodology Transparency",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Clearly explains the signal-vs-noise methodology: which heuristics were used, how false positives were filtered, what thresholds were applied, and what the limitations are",
+            "3": "Mentions methodology at a high level but lacks specifics",
+            "1": "No methodology explanation — trends appear to be selected arbitrarily",
+            "0": "No methodology"
+          }
+        }
+      ],
+      "expectedScoreWithout": 15,
+      "expectedScoreWith": 55
+    }
+  ]
+}

package/tests/smoke.json

@@ -0,0 +1,54 @@
+{
+  "version": "0.0.1",
+  "timeout": 60,
+  "tasks": [
+    {
+      "id": "smoke-01",
+      "description": "Track KOL opinions on an emerging technology topic with bot detection and trend context",
+      "input": "Monitor Twitter/X for key opinion leaders discussing the impact of new EU AI regulation on the tech startup ecosystem. Identify the dominant narratives, track which KOLs are driving the conversation, and flag any bot-driven amplification. I need a structured intelligence briefing with confidence ratings.",
+      "rubric": [
+        {
+          "criterion": "Source Curation & KOL Identification",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Identifies 5+ relevant KOLs across multiple tiers (tech policy experts, startup founders, regulatory analysts); constructs targeted queries using from: operators and topic keywords; sets appropriate temporal window",
+            "3": "Identifies 2-3 relevant accounts but misses important KOL tiers or uses overly broad queries",
+            "1": "Generic keyword search with no specific KOL targeting or source curation",
+            "0": "No source curation attempted"
+          }
+        },
+        {
+          "criterion": "Signal Filtering & Bot Detection",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Applies multi-layer filtering (bot removal, deduplication, relevance scoring); explicitly checks for bot amplification signals; reports both raw and filtered metrics; flags inauthenticity risks",
+            "3": "Some filtering applied but bot detection is incomplete or not quantified",
+            "1": "Minimal filtering; treats all engagement as organic",
+            "0": "No filtering or bot detection"
+          }
+        },
+        {
+          "criterion": "Opinion & Trend Analysis",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Extracts distinct stance clusters (supporters, critics, neutrals) with attributed KOL positions; detects trend velocity and sentiment direction; accounts for sarcasm and tone; includes temporal context",
+            "3": "Identifies general sentiment but lacks stance clustering or temporal analysis; tone detection is basic",
+            "1": "Surface-level sentiment without stance attribution or trend context",
+            "0": "No opinion or trend analysis"
+          }
+        },
+        {
+          "criterion": "Output Structure & Confidence",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Follows structured briefing format: executive summary, key findings with source attribution, KOL positions table, trend metrics, bot assessment, confidence rating with justification, and recommended actions",
+            "3": "Partially structured output with some elements missing (e.g., no confidence rating or no recommended actions)",
+            "1": "Unstructured narrative summary without clear sections or source attribution",
+            "0": "Raw data dump with no organization"
+          }
+        }
+      ],
+      "passThreshold": 60
+    }
+  ]
+}