Detect buying signals across TAM companies

Signal Scanner

Scheduled scanner that detects buying signals on TAM companies and watchlist personas, writes them to the signals table, and sets up downstream activation.

When to Use

• After TAM Builder has populated companies and personas
• As a recurring scan (daily/weekly) to detect timing-based outreach triggers
• When you need to move from static lists to intent-driven outreach

Prerequisites

• SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY in .env
• APIFY_TOKEN in .env (for Phase 2 signals)
• ANTHROPIC_API_KEY in .env (optional, for LLM content analysis)
• TAM companies populated via tam-builder
• Watchlist personas created for Tier 1-2 companies

Signal Types

Priority	Signal	Level	Source	Cost
P0	Headcount growth (>10% in 90d)	Company	Data diffs	Free
P0	Tech stack changes	Company	Data diffs	Free
P0	Funding round	Company	Data diffs	Free
P0	Job posting for relevant roles	Company	Apify linkedin-job-search	~$0.001/job
P1	Leadership job change	Person	Apify linkedin-profile-scraper	~$3/1k
P1	LinkedIn content analysis	Person	Apify linkedin-profile-posts + LLM	~$2/1k + LLM
P1	LinkedIn profile updates	Person	Apify linkedin-profile-scraper	~$3/1k
P2	New C-suite hire	Company	Derived from person scans	Free

Config Format

See configs/example.json for full schema. Key sections:

• client_name — which client's TAM to scan
• signals.* — enable/disable each signal type with thresholds
• scan_scope — filter by tier, status, lead_status

Database Write Policy

CRITICAL: Never write signals or update lead statuses without explicit user approval.

The signal scanner writes to multiple tables: signals (insert), enrichment_log (insert), companies (patch snapshots), and people (patch lead_status). These writes affect downstream outreach decisions — bad signals lead to bad outreach timing.

Required flow:

1. Always run --dry-run first to detect signals without writing to the database
2. Present the dry-run results to the user: signal count, types, top signals, affected companies/people
3. Get explicit user approval before running without --dry-run
4. Only then run the actual scan that writes to the database

Why this matters:

• Signals drive outreach timing — incorrect signals trigger premature outreach
• lead_status changes from monitoring to signal_detected are hard to undo across many records
• Snapshot updates affect future signal diffs — bad snapshots cascade into future scans
• Enrichment log entries track Apify credit spend

The agent must NEVER pass --yes on a first run. The --yes flag is only for pre-approved scheduled scans where the user has already validated the signal detection logic.

Usage

# Dry run first (ALWAYS DO THIS) — detect signals without writing to DB
python skills/capabilities/signal-scanner/scripts/signal_scanner.py \
  --config skills/capabilities/signal-scanner/configs/my-client.json --dry-run

# Full scan (only after user reviews dry-run results and approves)
python skills/capabilities/signal-scanner/scripts/signal_scanner.py \
  --config skills/capabilities/signal-scanner/configs/my-client.json

# Test mode (5 companies max)
python skills/capabilities/signal-scanner/scripts/signal_scanner.py \
  --config configs/example.json --test --dry-run

# Free signals only (skip Apify)
# Set all Apify signals to enabled: false in config

Flags

Flag	Effect
--config PATH	Path to config JSON (required)
--test	Limit to 5 companies, 3 people
--yes	Auto-confirm Apify cost prompts. Only use for pre-approved scheduled scans.
--dry-run	Detect signals but don't write to DB. Always run this first.
--max-runs N	Override Apify run limit (default 50)

Output

Signals table writes

Each signal includes: client_name, company_id, person_id, signal_level (company or person), signal_type, signal_source, strength, signal_data (JSON), activation_score, detected_at, acted_on, run_id.

Other database writes

• Person lead_status updated to signal_detected when activation_score >= threshold
• Company metadata._signal_snapshot updated for next diff cycle
• Person raw_data._signal_snapshot updated for next diff cycle
• enrichment_log entries with tool='apify', action='search' or 'enrich', plus credits_used

Console output

• Summary stats printed to stdout

Activation Score

activation_score = strength * recency_multiplier * account_fit

Recency:   <24h = 1.5, 1-3d = 1.2, 3-7d = 1.0, 1-2w = 0.8, 2-4w = 0.5
Account:   Tier 1 = 1.3, Tier 2 = 1.0, Tier 3 = 0.7

Connects To

• Upstream: tam-builder (provides companies + people)
• Downstream: cold-email-outreach (acts on signals)

File Structure

signal-scanner/
├── SKILL.md
├── configs/
│   └── example.json
└── scripts/
    └── signal_scanner.py