intel

name	intel
description	Gather and shape intelligence signals from collected feeds (RSS, HackerNews, EDGAR) into audience-aware output. Use when you need current context on a technology, industry trend, or domain — or when you need to present signals to a specific audience. NOT for forward-looking predictions (use forecast); NOT for architecture analysis (use archobs); NOT for writing specs (use spec).
metadata	{"stage":"Define","tags":["intelligence","trends","signals","research","briefing","news","feeds","evidence","audience","executive","engineering","decision","digest","synthesis","presentation","stakeholder"],"aliases":["intel","intelligence","signals","executive-brief","daily-digest","decision-brief"]}

Intel (Intelligence Briefs)

Overview

Produce focused intelligence briefs on a topic by querying the intel CLI against locally collected feeds (RSS, HackerNews, EDGAR). Briefs combine trending signals, full-text search hits, and topic breakdowns into a concise, evidence-backed summary an agent or human can act on.

Use this skill when you need current signal on a technology, vendor, standard, or industry trend — or when you need to present signals to a specific audience.

Success looks like: a brief with ranked signals, source citations, and a clear "so what" tailored for the target audience — readable in under 2 minutes and actionable without needing to parse raw data.

Prerequisites

1. Build the tool:

   cd tools/intelligence && npm install && npm run build
   

2. Make intel available on PATH:

   npm link          # from tools/intelligence/
   

3. Create a config file:

   mkdir -p ~/.config/intel ~/.local/share/intel
   cp config/feeds.example.yaml ~/.config/intel/config.yaml
   # Edit ~/.config/intel/config.yaml to customize feeds
   

4. Seed the database (first run):

   intel collect --once
   

5. Install the collector as a background service so data stays fresh:

   ./service/install.sh        # macOS (launchd) / Linux (systemd)
   

   This installs a LaunchAgent (macOS) or systemd user unit (Linux) that starts on login and restarts on crash. Verify it's running:

   # macOS
   launchctl print gui/$(id -u)/com.intel.collector
   tail -f ~/Library/Logs/intel-collector.log
   
   # Linux
   systemctl --user status intel-collector
   journalctl --user -u intel-collector -f
   

   To uninstall: ./service/install.sh uninstall

6. Verify: intel stats — check events_total > 0 and newest_event is recent.

Inputs / Outputs

Inputs: Topic scope (what to research); audience type (practitioner/executive/engineering/decision/digest/architecture); time window. Outputs: Audience-formatted intelligence brief with ranked signals, source citations, and "so what." Consumed by forecast (as data source), plan (as context), architecture (as ecosystem evidence).

Chooser

Content type (what data to gather)

Type	When to use
Topic brief (default)	"What's happening with X?"
Trend scan	General landscape check
Evidence pack	Feeding context into another skill
Source check	Verify data quality

Audience (how to present — default: practitioner)

Audience	Shape	When to use
Practitioner (default)	Ranked signals, trend context, gaps, so what	Feeding into your own work
Executive	3-5 bullet TL;DR, "so what", recommended action, risk flags	Status updates, steering meetings
Engineering	Signals mapped to stack, migration/deprecation implications	Sprint planning, tech radar
Decision	Evidence mapped to options, recommendation	Buy-vs-build, adopt-vs-wait, vendor selection
Daily digest	Top-5 signals, one-line commentary	Morning standup, async channel
Architecture decision	Archobs risk + forecast lifecycle × decision options	Technology adoption, boundary redesign

Clarifying Questions

• What topic or domain do you want a brief on?
• What time horizon matters? (last few hours, last week, last month)
• Is this for general awareness or feeding into a specific decision?
• Any particular sources or subtopics to prioritize?
• Who is the audience for this brief?
• Which brief type fits? (practitioner, executive, engineering, decision, daily digest, architecture decision)

Workflow

1. Determine content type and audience — ask or infer from context. If unclear, default to practitioner audience with topic brief.

2. Verify data freshness:

   intel stats
   

   Check total_events and newest_event — if the database is empty or stale, run intel collect --once first.

3. Gather signals (choose based on content type):

   Topic brief — run in parallel:

   intel search "<topic>" --since 7d --limit 20
   intel trends --window 60m --top 10
   intel topics --active
   

   Trend scan:

   intel trends --window 60m --top 15
   

   Evidence pack:

   intel pack --since 6h --top 10 --max-events 5
   

   Source check:

   intel sources
   

4. Audience-specific signal gathering (in addition to content type above):

   Executive / Daily digest:

   intel pack --since 24h --top 10 --max-events 5
   

   Engineering — run in parallel:

   intel pack
   intel search "<stack-relevant terms>"
   intel topics --active
   

   Decision — run in parallel:

   intel search "<decision topic>"
   intel trends
   

   Architecture decision — requires archobs + forecast data:

   archobs show clusters --format json
   archobs show risks --format json
   intel forecast    # lifecycle phases for relevant technologies
   

5. Deepen on high-signal hits — for the most relevant results, fetch full event detail:

   intel events --id <event_id>
   

6. Record decisions (optional) — when signals inform a decision, record it in the journal for cross-session memory:

   intel journal add --context "Evaluating queue options after SQS outage signals" \
     --decision "Stay with SQS, add DLQ" \
     --rationale "Outage was regional, DLQ covers failure mode" \
     --tags "infrastructure,messaging"
   

   Review past decisions:

   intel journal list --since 30d --tag "infrastructure"
   intel journal search "SQS"
   

7. Filter and rank — select the top signals by relevance to the audience:

   • Practitioner: prioritize signal strength and relevance to stated topic
   • Executive: prioritize business impact, risk, competitive signals
   • Engineering: prioritize stack relevance, deprecations, security advisories
   • Decision: prioritize evidence that differentiates the options
   • Daily digest: prioritize breadth and recency
   • Architecture decision: prioritize signals that affect boundary/technology choices

8. Synthesize the brief using the output template for the chosen audience (see below). Do not mix templates.

9. Flag gaps — note stale sources, missing coverage, low-confidence signals.

Minimum viable execution

When context or time is constrained, these are the load-bearing steps:

1. Check data freshness (step 2) — intel stats must show recent data.
2. Gather signals (step 3) — run the queries for the selected content type.
3. Synthesize the brief (step 8) — through the output template for the chosen audience. No raw JSON.

Steps that can be cut under pressure: audience-specific additional queries (step 4), deepening on high-signal hits (step 5), decision journal recording (step 6), gap flagging (step 9).

Guardrails

• Do not present intel output as authoritative fact — these are signals from configured feeds, not exhaustive research.
• Do not skip the freshness check — stale data produces misleading briefs.
• Do not dump raw JSON to the user — always synthesize into the output template.
• Do not run intel collect in long-running daemon mode during a brief — use --once if a refresh is needed.
• Do not mix brief types — pick one audience and commit.
• Do not fabricate signals — only use data returned by intel commands.
• Executive briefs must be readable by non-technical stakeholders — no jargon, no acronyms without expansion.

Common failure modes

• Presents raw signal data instead of synthesizing for the audience — dumps search results or trend tables without interpretation or "so what."
• Doesn't check data freshness before reporting — produces misleading briefs from stale or empty databases.
• Anchors on high-volume, over-classified topics (e.g., lang.typescript) — these get broadly assigned by the classifier and titles may not be topically relevant even when marked "high."
• Wrong audience framing — uses engineering jargon in an executive brief, or buries the "so what" in a practitioner brief.

Output Template

Practitioner (default)

• Topic: the subject of the brief
• Data window: time range covered, event count, source count
• Top signals (3-5): title, source, timestamp, why it matters
• Trend context: what's rising/falling, velocity of change
• Gaps: stale sources, missing coverage areas, low-confidence signals
• So what: 1-2 sentence synthesis of what this means for the user's context
• Next skill: where to go from here (plan, spec, architecture, etc.)

Executive

• Headline: 1 sentence — what's the most important thing to know
• Top signals (3-5 bullets): plain language, no jargon, each with why it matters
• So what: 1-2 sentences — implication for us specifically
• Recommended action / next step: what to do with this information
• Risk flags (if any): things that could go wrong if we ignore this

Engineering

• Data window: time range covered, event count, source count
• Signals by relevance to our stack: grouped by topic (e.g., runtime, framework, infra, tooling)
• Migration / deprecation watch: things to track that may force future work
• New tools / releases worth evaluating: notable releases relevant to our stack
• Security advisories (if any): CVEs, supply-chain risks, dependency alerts
• Links to deeper reads: URLs from source events for follow-up

Decision

• Decision statement: what we're choosing between (frame as a clear question)
• Evidence for each option: sourced from signals, with citations
• Gaps in evidence: what we don't know and how it affects confidence
• Recommendation: selected option with confidence level (high / medium / low)
• Next skill: plan or spec to act on the decision

Daily Digest

• Date + data window: date, time range, source count
• Top 5 signals: title + one-line take for each
• One thing to watch: emerging trend that hasn't peaked yet
• Source health note (if degraded): flag stale or unreachable sources

Architecture Decision

• Decision statement: what we're choosing between
• Structural context (from archobs): cluster coupling, boundary health, risk scores for affected areas
• Ecosystem context (from forecast): lifecycle phase, chain activity, system dynamics for relevant technologies
• Cross-domain synthesis: where structural reality and ecosystem signals align or conflict
• Options matrix: each option scored against structural + ecosystem evidence
• Recommendation: selected option with confidence level
• Next skill: plan or spec

Command Reference: Decision Journal

The decision journal closes the signal-to-decision loop. Record decisions alongside the signals that informed them for cross-session memory.

# Record a decision
intel journal add --context "..." --decision "..." [--rationale "..."] [--tags "a,b"] [--refs '[{"type":"event","id":"rss:test:1"}]']

# List recent decisions
intel journal list [--since 7d] [--tag "..."] [--limit 20] [--cursor ...]

# Search decisions
intel journal search <query> [--since 7d] [--limit 20]

• context: What situation prompted the decision
• decision: What was decided
• rationale: Why this option was chosen (optional)
• tags: Comma-separated freeform tags for filtering
• refs: JSON array of signal references linking to events or topics

Training Data Generation

Generate labeled training data for classifier evaluation and evolution. This workflow produces a training set, loads the taxonomy, and uses batched subagent classification to label each event independently.

Phase 1: Generate

intel training-set generate --sample-rate 0.1
# or with reproducible seed:
intel training-set generate --sample-rate 0.1 --seed 42

Capture the output path for Phase 3.

Phase 2: Load taxonomy

intel topics

Run intel topics once to capture the full topic taxonomy (66 topics across 10 categories). Include this output verbatim in each subagent prompt — do not re-fetch per batch.

Phase 3: Classify (batched subagent loop)

Iterate in batches of 25 events:

1. Call intel training-set next <db> --limit 25 to get a batch of unreviewed events (machine labels omitted by default to prevent anchoring)
2. Spawn up to 25 subagents in parallel (via Task tool), each with one event's title, content, url, source, feed, and the taxonomy from Phase 2
3. Each subagent reads its event independently, assigns 1-5 topics (targeting ≤3), and returns the classification
4. As subagents complete, call intel training-set label <db> <event-id> --topics <csv> --labeler haiku for each result
5. Call intel training-set progress <db> every 5 batches (~125 events) to check completion
6. Repeat until remaining reaches 0 or the requested event count is reached

Subagent classification protocol:

• Each subagent receives: event title, content (truncated to ~4,000 chars), url, source, feed, and the full taxonomy
• Assign 1-5 topics (target ≤3). Assign 4-5 only for genuinely cross-domain events.
• Do not pass --show-machine-labels — blind classification prevents anchoring
• Do not pass score or comments to subagents — engagement metrics would anchor classification
• If no topic matches, return empty topics (--topics "" stores [])
• Use model: "haiku" for subagents — topic classification from a fixed taxonomy is within haiku's capabilities

Partial labeling: The workflow supports interruption and resumption. Specify an event count (e.g., "classify 500 events") as an orchestrator-level limit. Partial training sets are useful for precision estimates on topics with sufficient samples (≥30).

Guardrails:

• Do not modify the source intelligence database
• Do not skip events — even uninteresting events must be classified for unbiased precision
• Do not pass --show-machine-labels for classification — blind output only
• If a subagent fails, skip the event and continue — it remains unreviewed for a future batch

Command Reference: Training Set

# Generate training set
intel training-set generate [--sample-rate 0.1] [--output <path>] [--seed <n>] [--dry-run]

# Get next unreviewed events
intel training-set next <training-db> [--limit 25] [--show-machine-labels]

# Label an event
intel training-set label <training-db> <event-id> --topics "topic1,topic2" [--labeler haiku] [--notes "..."]

# Check progress
intel training-set progress <training-db> [--verbose]

# List training databases
intel training-set list [--dir <path>]

# Export labeled data
intel training-set export <training-db> [--output <path>] [--reviewed-only] [--raw]

# Evaluate classifier accuracy
intel training-set evaluate <training-db> [--min-samples 30] [--labeler haiku]

# Train CNB classifier (requires ≥500 labeled events)
intel classifier train <training-db> [--output <path>] [--min-examples 20] [--validation-split 0.2]

References

• Forward-looking predictions: forecast
• Architecture observability: archobs
• Implementation planning: plan
• Spec-driven development: spec
• Architecture decisions: architecture