pulse – Data & Science skill for AI agents

Pulse — Multi-Source Recency Research

> Portability: Works in Claude Code CLI and Claude.ai. Phase 4 accepts a local X/Twitter search export before trying a live interface.

A recency-oriented research skill that synthesizes what people are saying about a topic across Reddit, Hacker News, the open web, and (optionally) X/Twitter — within a configurable time window. Output is a single coherent briefing with citations, engagement signals, and cross-platform pattern analysis. The skill captures the current conversation, not the canonical reference.

Invocation

Explicit trigger phrases:

• "pulse on [topic]"
• "what's happening with [topic]"
• "what are people saying about [topic]"
• "current conversation about [topic]"
• "take the pulse of [topic]"
• "trending: [topic]"
• "find me info on [topic]"

Also covers: competitor research with recency flavor, trend discovery, tool comparisons, audience sentiment analysis.

Agent Integrity Rules (Research-Pack Convention)

The following rules apply throughout the run. They are inherited from the research-pack convention and locked down by PR #657's cross-skill consistency audit.

• Execution discipline. Phases 1–3 run in parallel (Reddit + HN + Web are independent). Within each phase, sequential calls only. 1 q/sec rate limit per platform. Confirm response received before next call within the same phase.
• Source discipline. Cite only sources returned by this session's tool calls. Training knowledge is labeled [Background — not from search] and excluded from primary findings count.
• Three-count tracking. Queries sent / sources received (shown) / sources cited. Surfaced in the audit log inline in the synthesis section. Use scripts/citation_tracker.py for the deterministic count.
• Retry policy. On failure → wait 3s → retry once → log. After 3 consecutive failures across all sources: stop, alert user, share what was collected. Never deliver an empty file.
• Plan-tier detection. Reddit + HN are unauthenticated public JSON APIs (rate-limited per IP, not per plan). Surface rate-limit signals from response headers when available; degrade gracefully otherwise.

See references/research_pack_conventions.md for the canon and references/parallel_execution_discipline.md for the rate-limit rationale.

Phase 0: Grill-Me Intake (2–4 forcing questions, one at a time)

Dependency-ordered. Each question carries explicit "why I'm asking". Stop condition: max 4.

Q1 (root) — Topic Specificity

> What's the topic? State it in 1–2 sentences — be specific. "AI" or "tech" will get you a vague survey; "self-hosted LLM deployment for small teams" or "Claude Code adoption among enterprise engineering orgs" will get you a useful answer.

>

> *Why I'm asking:* Specificity dictates search quality. Vague topics produce vague briefings. If your topic is broad, I'd rather narrow it now than spend a search budget on noise.

Refuse mush. If the user says "AI", push back once: "What about AI — adoption, safety, capability, regulation, or comparison? Pick an angle." If the user still won't narrow after one push-back, deliver with the explicit "vague topic — survey level, not depth" caveat.

Q2 (depends on Q1) — Angle

> What angle matters most? Pick one:

>

> 1. Trend — what's accelerating or decelerating

> 2. Sentiment — what people feel about it

> 3. Problems — pain points and complaints

> 4. Opportunities — gaps and unmet needs

> 5. Comparison — how it stacks up against alternatives

>

> *Why I'm asking:* The angle dictates which sources weight more (Reddit for sentiment, HN for technical critique, Web for trend coverage) and how I rank the synthesis.

Forcing choice. Recommended default: trend, unless the topic obviously calls for a different angle.

Q3 (always) — Time Window

> Time window: 7 / 14 / 30 / 60 / 90 days? Default is 30.

>

> *Why I'm asking:* 7 days catches breaking conversation; 90 days catches sustained narrative shift. Pick based on how recent the news matters.

Forcing choice with default.

Q4 (depends on Q1) — Platform Scope

> Any platform to skip? By default I'll cover Reddit + Hacker News + open web, plus X/Twitter if browser automation is available. Skip any you don't care about.

>

> *Why I'm asking:* Skipping a platform saves search budget. Reddit dominates sentiment; HN dominates technical critique; Web dominates breadth; X dominates breaking conversation. Skip what doesn't fit your angle.

Asked only if Q1 + Q2 suggest some platforms are clearly off-target (e.g., consumer sentiment topic → HN less useful). Otherwise default to "all platforms".

Stop condition: After Q4 (or earlier with dependency skips), commit and start Phase 1. Max 4 questions, never bundle.

Pre-flight

Before any phase fires:

1. Compute the time window with scripts/time_window_calculator.py --window <Nd>. Get back the Unix timestamp for created_at_i> (HN) and the t= parameter (hour|day|week|month|year|all) for Reddit.

2. Generate the output slug with scripts/topic_slug_generator.py --topic "<topic>" --date $(date +%Y-%m-%d). Detect if ${RESEARCH_DIR}/pulse/<slug>-<date>.md already exists; if yes, append -v2 suffix or warn user.

3. Start the three-count audit log with scripts/citation_tracker.py --action start --session pulse-<date>-<slug>. This file at ~/.pulse_sessions/<session>.json persists across the run.

Phase 1: Reddit (parallel with HN + Web)

API: reddit.com/search.json (unauthenticated, public JSON).

Queries (sequential within Reddit, 1 q/sec):

1. sort=top&t=<window>&q=<topic> — top posts in window

2. sort=new&t=<window>&q=<topic> — new posts in window (catches breaking signal)

3. For each of the top 3–5 posts by score: fetch the comments JSON (<post-url>.json?limit=top) for the top 10–20 comments.

Headers / rate limits. Reddit rate-limits by IP, not plan. Throttle to 1 q/sec. If response has X-Ratelimit-Remaining: 0 or returns 429, wait 3s, retry once. If still failing, fall back to subreddit-restricted search (r/<topic-subreddit>/search.json) or ?raw_json=1.

Record each query: citation_tracker.py --action record_sent --session NAME --query "...".

Record received counts: citation_tracker.py --action record_received --session NAME --count N.

Phase 2: Hacker News (parallel with Reddit + Web)

API: Algolia HN search (hn.algolia.com/api/v1/).

Queries (sequential within HN, 1 q/sec):

1. search?query=<topic>&numericFilters=created_at_i><timestamp>&tags=story — stories in window

2. search?query=<topic>&numericFilters=created_at_i><timestamp>&tags=comment — comments in window (catches discussion signal)

Failure handling. If HN returns empty: broaden the query (remove uncommon nouns); if still empty, drop the timestamp filter as last resort and label results "outside window".

HN bias note. HN skews technical / builder. Surface this in synthesis: "HN's voice is implementation-oriented; consumer sentiment will be under-represented here."

Phase 3: Web Search (parallel with Reddit + HN)

Tools: Available web search + fetch (e.g., WebSearch + WebFetch).

Query strategy (sequential within Web, 1 q/sec):

1. Trusted publishers — "<topic>" site:nytimes.com OR site:wsj.com OR site:wired.com OR site:theverge.com OR site:techcrunch.com after:<date>

2. Recent reviews — "<topic>" review <year> or "<topic>" "honest review" after:<date>

3. Honest-opinion sources — "<topic>" problems OR complaints OR "worth it" after:<date>

Fetch the top 3–5 URLs per query. Truncate at the body, skip cookie/nav markup.

Citation discipline. Every claim in the Web section must trace to a fetched URL. Do NOT cite from snippets alone; fetch first.

Phase 4: X/Twitter (sequential, optional)

Run last. Reasons:

• Most likely to fail / require browser automation
• X content overlaps significantly with Reddit/HN — so it adds delta, not primary signal

Interface (in priority order):

1. User-provided JSON export. Import it before any live request:

   python3 scripts/citation_tracker.py \
     --action import_sources \
     --session NAME \
     --input /path/to/x-search.json \
     --platform x \
     --since 2026-07-01T00:00:00Z \
     --until 2026-08-01T00:00:00Z
   

The importer accepts Xquik Tweet Search, X API v2, and generic JSON exports.

It normalizes legacy and snake-case fields, joins X API includes.users,

filters the requested window, and deduplicates by Tweet ID. It makes no

network calls and requires no API key. The audit stores the filename and

SHA-256 digest, not the user's absolute path.

2. Grok if available in the harness.

3. X API if authenticated.

4. Browser automation if the harness supports it.

5. Skip with note if none of the above are available.

Documented behavior:

> If Phase 4 is skipped: include the section heade

… (full content is in the download package)