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 significantly with Reddit/HN — so it adds delta, not primary signal **Interface (in priority order):** 1. **Grok** if available in the harness 2. **X API** if authenticated 3. **Browser automation** if the harness supports it (Claude Code CLI with `playwright` or similar) 4. **Skip with note** if none of the above available **Documented behavior:** > If Phase 4 is skipped: include the section header `## X/Twitter` with body `Skipped — [reason: no browser automation / no Grok / no X API]`. Do NOT pretend to have data. ## Synthesis (Cross-Platform Patterns) After Phases 1–4 complete (or Phase 4 skipped), produce the synthesis: 1. **Consensus signals** — points where 3+ platforms agree (highest confidence). Tag each with cited source URLs. 2. **Controversy signals** — points where platforms disagree. Note who says what. 3. **Pain points** — recurring complaints across sources (esp. Reddit + Web). 4. **Excitement signals** — recurring enthusiasm (esp. HN + X if available). 5. **Emerging trends** — first-time mentions in newest posts but absent from older ones (compare `sort=new` vs `sort=top`). 6. **Gaps** — what's notably absent that you'd expect to find. For each pattern, **cite the source URLs** that support it. Use `citation_tracker.py --action record_cited --session NAME --url "..."` per citation. See `references/cross_platform_synthesis.md` for detection heuristics. ## Output Save to file AND paste in chat: **File:** `${RESEARCH_DIR}/pulse/<topic-slug>-<YYYY-MM-DD>.md` (path from `topic_slug_generator.py`). **Format:** ```markdown # [TOPIC] — Pulse (Last [N] Days) *Generated: [DATE] | Angle: [Q2 choice]* ## TL;DR [2-3 sentences max] ## Reddit ### Top Posts - **[Title]** (r/sub) — [score, comments] — [summary] — [URL] ### What Reddit Is Saying [Narrative paragraph] ## Hacker News ### Notable Stories - **[Title]** — [points, comments] — [summary] — [URL] ### What HN Is Saying [Narrative paragraph; note HN's technical/builder bias] ## Web ### Key Sources - **[Title]** ([Publication]) — [takeaway] — [URL] ### What the Web Is Saying [Narrative paragraph] ## X/Twitter (if available) [Cleaned response, with handles/references preserved] [Or: "Skipped — [reason]"] ## Cross-Platform Patterns [Highest-confidence signals across sources] ## Key Takeaways - [3-5 bullets] ## Content Angles (if applicable) [2-3 specific angles supported by the data] --- *Audit:* Queries sent: N (Reddit: a, HN: b, Web: c, X: d|skipped). Sources received: M. Sources cited: K. Training knowledge: 0 ([Background] excluded from count). ``` ## Error Handling | Failure | Behavior | |---|---| | Topic is too vague (Q1) | Refuse to start. Re-ask Q1 once with examples. After 1 push-back, deliver with "vague topic" caveat. | | Reddit blocks / rate-limits | Try `?raw_json=1` or fall back to subreddit-restricted search. Honor 3s-retry. | | HN returns empty | Broaden query, drop timestamp filter as last resort, label results "outside window". | | Web search returns nothing useful | Note in output; don't fabricate sources. | | Browser automation unavailable | Skip Phase 4 with documented note. | | WebFetch times out | Use what loaded, mark the source as "truncated". | | 3 consecutive failures across sources | Stop. Return what was collected with explicit "stopped early" note. Do NOT deliver empty file. | | All sources fail | Return error with diagnostic info. Do NOT deliver empty file. | ## Tooling | Script | Role | |---|---| | `scripts/time_window_calculator.py` | Compute Unix timestamps + Reddit `t=` parameter from window string (`30d`, `7d`, etc.). Deterministic from `datetime.now()`. | | `scripts/citation_tracker.py` | JSON-backed three-count audit log (sent / received / cited) at `~/.pulse_sessions/<session>.json`. | | `scripts/topic_slug_generator.py` | Filesystem-safe slug + duplicate-date detection for output paths. | ## References - `references/research_pack_conventions.md` — Agent Integrity Rules canon (7+ sources: Google SRE, Reddit API docs, Algolia HN docs, exponential-backoff literature, citation discipline) - `references/cross_platform_synthesis.md` — consensus / controversy / pain detection across platforms (7+ sources) - `references/parallel_execution_discipline.md` — 1 q/sec rationale + plan-tier signals (7+ sources) ## Anti-Patterns To Reject - Starting any search before the user commits to topic specificity (Q1) - Batching intake questions instead of one at a time - Hardcoded URLs that won't survive API changes (note format, explain may evolve) - Specific person / brand references in the skill body - Tight coupling to one X/Twitter interface - Missing fallback behavior on source failure - "Just use [specific tool]" without explaining what the tool does - Citing training knowledge in the cited count - Fabricating sources to fill out a section --- **Version:** 1.0.0 **Source spec:** [`megaprompts/01-pulse-megaprompt.md`](../../../../megaprompts/01-pulse-megaprompt.md) **Build pattern:** Path B (direct conversion). Re-grill with `/cs:grill-with-docs` if drift between spec and implementation surfaces.