Newsjack Detector

Newsjack Detector

Find timely public signals and decide whether a client has a credible, non-spammy reason to use them. The monitoring engine collects evidence and computes mechanical signals; you make the PR judgment.

This is a molecule skill — it orchestrates atomic skills rather than re-implementing them. Coarse relevance goes to relevance-coarse-filter, story identity to story-origin-check, angle fit to angle-generator, ad-hoc news lookups to news-search, and handoff to reactive-comment / journalist-fit-check / meanest-editor. Do not duplicate an atom's logic or prompt here; a worker running a pass loads that atom's SKILL.md directly, so the atom stays the single source of truth.

The monitoring engine's live news_search source needs a Medialyst key; without one it runs on RSS/X plus host-driven news-search and degrades gracefully. Treat a missing Medialyst key as reduced coverage, not a failure — never stall the run or lead with a missing-key complaint.

Runtime Mode

Newsjack Detector has two runtime modes:

• Full Mode: Use this in Claude Code, Codex, OpenClaw, Hermes, or another capable agent harness with shell, filesystem, network, and local CLI access. Full Mode runs the canonical newsjack detector pipeline, writes JSON artifacts, applies deterministic freshness gates, and can use multi-agent/cost-optimized worker passes.
• Limited Mode: Use this in Claude.ai chat, ChatGPT chat, Claude Cowork, or any restricted runtime without shell/filesystem/CLI access. Do not attempt curl, npm, or on-demand CLI installation. Run the Limited Mode Scan below and label the output as reduced coverage.

Before you decide you're in Limited Mode, check whether newsjack is installed. It ships as a prebuilt, bundled binary — you do not need Go, a compiler, or any build/install step to run it. Never look for a Go toolchain, and never declare the CLI "missing" or tell the user they need a "Go environment" without running this check first:

1. Run newsjack --version. If it prints a version, you're in Full Mode — use plain newsjack ... for every command.
2. If newsjack isn't on PATH, try the bundled location ~/.newsjack/bin/newsjack --version. If that prints a version, use that full path in place of newsjack everywhere below.
3. Only if both fail (and you genuinely have no shell) are you in Limited Mode.

The bundled binary is almost always already installed — assume Full Mode and verify, don't assume it's missing.

Required Workflow (follow in order)

Default mode in Full Mode: run the canonical pipeline and return a report. This skill exists to produce a freshness-gated newsjack report, including for scheduled/cron runs. Execute by default — only drop into discussion/planning when Step 2 is blocked. In Limited Mode, run a disclosed reduced-coverage scan instead.

1. CHECK DOCTRINE. If skills/ETHICS.md or skills/WHY-NOT-SPAM.md exist, follow them. This skill refuses tragedy hooks, fabricated standing, fake urgency, and spray-and-pray output. These blocks are absolute and override every later step.

1. ANCHOR THE CLIENT — ASK FIRST ONLY IF BLOCKED. Identify company, topics, competitors, spokespeople, standing, and client-specific exclusions, from a profile JSON or plain-text context.

• No profile and no usable client context → ask for it before running. Never invent profile facts.
• Genuinely ambiguous (which client? which topic? one-off vs recurring?) → ask one clarifying question, then proceed. Otherwise do not stall the run.
• Missing standing is not a blocker: monitor, but mark opportunities weak/no-standing.
• Load the client brief. Read the monitor's brief.md (its path is surfaced as brief_path by monitor run/monitor status, or it sits next to the profile). It is the source of truth for what this client will and won't pitch and how to present the scan — see Client Brief below. An empty/template brief carries no rules.

1. PICK THE RUN SHAPE.

• Restricted chat / no CLI / no filesystem → Limited Mode Scan below.
• One-off / "what's moving on X" → Quick Run below.
• Real judgment, agent run, or scheduled job → Canonical Pipeline below (the default for any output a human or pitch will rely on).
• Recurring / cron feed monitoring → Canonical Pipeline plus the recurring rules in Freshness Gate (--feed-only --new-only --max-age-hours 24, hard freshness gate).

1. RUN THE PIPELINE. Execute the chosen path end to end. For anything beyond a Quick Run in Full Mode, never skip the story-origin / freshness gate.

1. JUDGE — NEVER TRUST MECHANICS AS PERMISSION. routing.queue_priority and story_size are recall pressure, not pitch permission. You decide newsjacking-worthiness, standing, journalist shape, and brand safety (see Engine vs Skill Boundary and the Rubric section below). Gate angle fit through angle-generator.

1. VERIFY & CONCLUDE. In Full Mode, run the Completion Checklist, then report: the run.md path, whether coarse passes were cost-optimized or fallback, whether every surfaced signal has verified ≤24h first-public freshness, and top findings. In Limited Mode, state that no local artifacts, saved monitor state, or deterministic freshness gate were available.

Engine vs Skill Boundary

The Go CLI owns (mechanical, deterministic):

• ingestion, dedupe, clustering, novelty tracking
• mechanical scores only: freshness, source agreement, novelty, profile match, source quality, momentum, major-news weight
• deterministic story-size scoring from news-search metadata: log-scaled estimated monthly traffic + domain authority, with coverage spread across independently surfaced domains. When authority metadata is missing for a recognized major outlet, the engine may use a low-confidence known-outlet fallback. When publication metadata is otherwise sparse, the engine may attach a low-confidence story_size.attention_hint from deterministic source signals such as X News clusters, major public actors, and high-stakes event terms; this is recall pressure, not proof of magnitude.
• deterministic hygiene filtering for docs/help/product/SEO pages
• coarse-relevance application via newsjack filter-apply, plus two recall guards: a big-story guard that upgrades any reject of a high/major story_size signal to monitor_only (big_story_recall) — the cheap pass can never hard-drop a big story — and a profile-match guard that upgrades reject/no_profile_bridge to monitor_only when detector/profile evidence already matched the client, a competitor, or a profile term
• deterministic freshness gating via newsjack origin-apply
• operational routing: lane, queue priority, threshold-demotion flag
• deterministic safety flags

You own (PR judgment):

• whether the signal is newsjacking-worthy and whether the client has standing
• same-story / original-coverage judgment (via story-origin-check)
• final decay explanation from freshness_gate
• journalist shape, brand-safety judgment, and handoff to the next skill

Never treat routing.queue_priority as permission to pitch — it is only operational queue order.

Client Brief

Each monitor may carry a brief.md — a prose, user-owned statement of what this client will and won't pitch and how they want the scan presented. It is the source of truth for client pitch/output policy; the profile JSON governs collection, the brief governs what gets pitched and shown. The CLI only creates and surfaces the file (monitor init scaffolds it; brief_path is reported by monitor run/monitor status); it never parses it — reading and applying it is yours.

• Where it binds: triage and report rendering — never collection. Keep retrieval and the coarse pass brief-agnostic so nothing is dropped before judgment; the brief only decides what an already-collected, already-fresh item is allowed to be and how it's shown.
• Never pitch rules are hard: an item matching one can never be pitch_ready. A non-big item drops to watch (client_policy_exclusion); a fresh high/major item stays big_story with off_policy: true (the never-drop doctrine still holds — surface it, don't hide it). newsjack-triage enforces this.
• Audience / We pitch set the standing altitude: topical overlap is not pitchability. A story can be on-topic and still off-brief.
• How to surface is presentation only: collapse a section to a disclosed count, never silence it. Disclose what the brief held back (count + reason) so nothing is hidden.
• Feedback updates the brief. When the user reacts to a run — "too policy-heavy," "stop showing me X," "this is exactly right" — propose an edit to brief.md (a new We never pitch rule, a How to surface line, or a dated Example) so the policy is captured durably, not just for this run. Confirm the edit. An empty/template brief means run with defaults.

Profile Setup File

The monitor profile JSON is the source of truth for collection setup: a focused set of short broad beat topics, search terms, competitors, feeds, standing, spokespeople, and exclusions. Prefer 6-8 core 2-3 word topics, with one-word topics allowed when natural. If the user wants to change what the monitor looks for, edit the profile JSON rather than generating one-off retrieval terms during a detector run.

• Installed monitors keep the setup file at ~/.newsjack/monitors//profile.json; brief.md sits next to it.
• Direct detector runs use the file passed with --profile.
• Fixture profiles live under fixtures/newsjack-detector-agent/profile..json.

Use newsjack-monitor-setup when the user wants to create or materially revise a profile. Collection feedback such as "watch broader accounting firm news" belongs in profile.json (topics / search_terms / feed_urls): put 6-8 core broad beats in topics, and put broad retrieval terms plus named platforms/products/regulators/competitors in search_terms. Pitch-policy feedback such as "don't pitch policy stories" belongs in brief.md. After editing profile.json, rerun a mock or fixture smoke before trusting the next live run.

Limited Mode Scan

Use this path when running in Claude.ai chat, ChatGPT chat, Claude Cowork, or any runtime without shell/filesystem/CLI access.

Limited Mode is useful for PR judgment, not canonical monitoring. It does not create saved monitors, write JSON artifacts, keep seen-state, run source ingestion, apply the Go freshness gate, or use cost-optimized worker passes.

1. Anchor the client. Use a pasted profile, user context, website summary, or plain-text description. If there is no usable client context, ask for it.
2. Collect a small evidence set. Use pasted links first. If the runtime has web/search tools, search recent news for the profile topics, competitors, named regulators/platforms, and any explicit user topic. Keep the query list short and disclose it.
3. Build candidates manually. For each candidate, keep title, source, URL, apparent publication time, why it matched the client, and any safety concerns. Do not invent publication dates, outlet names, source counts, or traffic/authority scores.
4. Verify freshness where possible. Prefer primary/source-of-record pages and independent coverage. Treat unverified dates as freshness_unverified; do not pitch them as time-sensitive.
5. Apply PR judgment. Use this skill's doctrine, story-origin-check reasoning where possible, newsjack-triage for standing/routing, and angle-generator for any pitchable item.
6. Return an inline report. Use the same sections as Full Mode: Pitch-Ready, Big Stories Worth a Look, Watch / Context, plus a short Limited Mode Caveat that names missing capabilities and searches/evidence used.

Never call this a canonical detector run. If the user wants saved monitors, scheduled scans, deterministic freshness gates, local artifacts, or recurring seen-state, recommend Full Mode in Claude Code, Codex, OpenClaw, or Hermes.

Quick Run

One-off discovery and scans:

newsjack detector run --profile profile.json --save

The detector emits JSON only; render any human scan yourself from the artifact facts. Use --topic "explicit user topic" only when the user deliberately asks to add a one-off retrieval topic. Routine profile runs should rely on the profile's durable topics and search_terms, not ad hoc generated retrieval terms. Use --mock for local verification without credentials. Full flag/source/env reference: references/engine-cli.md.

For each queued signal, inspect title, sources, evidence URLs, age, routing.lane, mechanical_scores (major_news, novelty, source_agreement), profile matches, and safety flags. For x evidence inspect x_signal_type, x_social_signals, x_author_followers, x_query_counts; treat lone low-reach posts as noise. A high major_news means the story is broadly important, not that the client has standing. Treat engine age/decay as provisional until story-origin-check verifies the first-public clock. Then apply the Rubric section below and the Output Format.

Canonical Pipeline

The artifact contract is the source of truth. Write all artifacts to a timestamped run folder:

RUN_DIR/
  candidates.json              # 1. detector output
  coarse_relevance_decisions.json   # 2. coarse pass
  relevant_candidates.json     # 3. filter-apply
  clustered_candidates.json    # 3b. cluster — same-story dedup + stale pre-gate
  origin_findings.json         # 4. story-origin pass (representatives only)
  targeted_candidates.json     # 5. origin-apply (freshness authority)
  triaged_candidates.json      # 5b. newsjack-triage — standing + consolidation
  final_report.md              # 7. compiled 3-bucket scan (pitch-ready / big stories / watch)
  run.md                       # 8. skill-rendered — THE human-facing artifact
  detector.stderr.log  commands.log  summary.json

Only run.md is human-facing; the rest are provenance.

1. Run the detector and save candidates. This is the canonical invocation — use it verbatim for any run a human or pitch will rely on, across every harness, so runs stay comparable:

``bash newsjack detector run --profile profile.json --sources news_search,x --lookback-days 1 --depth quick --limit 80 --min-queue-priority 40 --min-major-news 0.55 > candidates.json ``

The floors --min-queue-priority 40 and --min-major-news 0.55 are the engine defaults; they define the emitted pool. Do not lower them and do not pass --include-all-scored or --no-hygiene-filter (debug-only) for a real run — they change which signals reach the report and make two runs of the same profile incomparable. Profile terms own durable retrieval; do not hand-tune the query per run unless the user explicitly asked for a one-off --topic. For recurring/cron precision add --demote-unmatched-x (see Freshness Gate); that is the only flag the canonical command grows.

1. Coarse relevance pass → coarse_relevance_decisions.json. High-recall junk removal only — no ranking, angles, dates, or pitch decisions. Each worker loads skills/relevance-coarse-filter/SKILL.md and applies it to its assigned signals; merge every worker's output into one decisions array. For model/worker routing and chunking, see references/harness-routing.md.

1. Apply coarse decisions:

``bash newsjack filter-apply --candidates candidates.json --decisions coarse_relevance_decisions.json --include keep --include monitor_only --output relevant_candidates.json ``

3b. Cluster same-story signals before the expensive retrieval pass:

``bash newsjack cluster --candidates relevant_candidates.json --drop-stale --window-hours 24 --output clustered_candidates.json ``

The Go CLI collapses syndicated pickups / near-duplicate headlines of the **s

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: elvisun
• Source: elvisun/newsjack
• License: MIT
• Homepage: https://newsjack.sh

Install and usage instructions live in the source repository linked above.