pulse

Pulse — Multi-Source Recency Research

Portability: Works in both Claude Code CLI and Claude.ai. The optional X/Twitter phase requires browser automation and is skipped automatically if unavailable.

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 sig