tam-mapping

name	tam-mapping
description	Build TAM databases from scratch using a 7-phase methodology (Source Discovery → Keyword Expansion → Config → Collection → Dedup → Exclusion → Enrichment hand-off). Triggers "tam map", "build tam", "total addressable market", "scrape industry", "map the market", "build a lead database", "venue partnerships tam", "labs tam", "residential tam", "installer tam". Entity-routed — Nites residential (Google Maps ZIP), Supply installer (SAM.gov + Houzz + state license dbs), Labs venue partnerships (Spider.cloud + AI Ark + Discolike + IcyPeas + BlitzAPI + Prospeo + MillionVerifier). Phase 4.5 cross-workspace EB exclusion is MANDATORY (HARD-FAIL on either workspace unreachable). Phase 5 enrichment is pluggable per ADR-008. Distinct from `list-building` (BC-2717 — assumes a TAM already exists via dbt audience views).
user-invocable	true
allowed-tools	mcp__plugin_marketing_salesforce__*, mcp__plugin_marketing_spider__*, mcp__plugin_marketing_aiark__*, mcp__plugin_marketing_discolike__*, mcp__emailbison-b2b__*, mcp__emailbison-personal__*, WebSearch, WebFetch, Read, Write, Bash
metadata	{"version":"0.1.0","upstream":"Revgrowth1/ai-gtm-workflows + Revgrowth1/tam-map@9f5c72e74b","category":"Outbound Lead Gen"}

TAM Mapping

A BDR, RevOps operator, or marketing lead with a new motion has two failure modes: spend weeks hand-curating a TAM (slow, inconsistent, miss 30–60% of the market) or run enrichment on a list that's 20–40% already-contacted (waste credits + sender reputation). This skill is the third option — a 7-phase pipeline that constructs a deduped, exclusion-filtered, optionally enriched/tiered TAM CSV ready for list-building or launch-campaign.

Reference-build calibration anchors (upstream Revgrowth 02): roofing TAM 20K sendable at $15, coffee shop TAM 11K sendable. Use as Nites/Supply scale anchors. Labs-path reference example in plugins/marketing/references/tam/examples/ (BC-5946).

Three entity routes:

• Nites residential — Google Maps ZIP scraping via WebSearch (absorbs Revgrowth 09 local-enrichment).
• Supply installer — SAM.gov federal contracts + Houzz + state license databases.
• Labs venue partnerships — full 8-provider stack from upstream Revgrowth1/tam-map: Spider.cloud crawl + AI Ark + Discolike + IcyPeas → BlitzAPI → Prospeo → MillionVerifier → tier delegation to icp-scoring rubric abc.

Distinct from list-building (BC-2717): that skill consumes a TAM (assumes a brite-data-platform dbt audience view exists). This skill constructs one when no audience view exists. If a vertical already has a dbt view, skip this skill and use list-building directly.

---

Before Starting

Check for product marketing context first. If docs/marketing-context.md exists, read it for entity-specific ICP and voice context. If the file does not exist, fall through to the missing-file fallback below — do not proceed with degraded inferred ICPs. Source taxonomy (Phase 1) and ICP gating (Phase 7) both depend on entity-correct context.

Entity detection

The skill builds a TAM for ONE Brite entity per invocation (Nites / Supply / Labs). Detection logic when --entity is not passed:

State	Behavior
marketing-context.md exists with one entity populated	Use it. Print: Using entity=<X> from marketing-context.md (override with --entity). Proceed.
marketing-context.md exists with multiple entities populated	Call AskUserQuestion listing the populated entities; user picks one.
marketing-context.md missing	Call AskUserQuestion with three options: (1) Exit and instruct user to run /marketing:product-marketing-context, then re-invoke tam-mapping after the file lands (recommended — no in-session pause/resume per user feedback). (2) Pick an entity for this run only with inline --entity <X> and --criteria-file <path> (does not save context). (3) Cancel.

Vertical detection (Labs path)

State	Behavior
--vertical matches a pre-loaded playbook	Lazy-load plugins/marketing/references/vertical-playbooks/{vertical}.md. 6 pre-loaded: zoos, aquariums, casinos, hotels-resorts, ski-resorts, sports-stadiums.
--vertical does NOT match a pre-loaded playbook	Treat as custom vertical. Require --criteria-file <path> (JSON ICP) OR prompt for inline ICP via AskUserQuestion. NEVER silently default.

Invocation flags

Flag	Default	Notes
--entity <X>	(auto-detect)	One of brite-nites, brite-supply, brite-labs.
--vertical <slug>	(required for Labs; optional for Nites/Supply)	Slug for output dir + Labs playbook lookup.
--criteria-file <path>	(auto-loaded from playbook for Labs pre-loaded verticals)	JSON criteria; required for custom verticals.
--output-dir <path>	(auto-derived)	Nites/Supply: docs/research/tam/{vertical}-{YYYY-MM-DD}/. Labs: docs/campaigns/labs/tam/{slug}/. Path-traversal segments (..) and absolute paths outside the worktree root are rejected.
--enrichment-provider <id>	(read from ${user_config.enrichment_provider})	Override per-run. Enum: `blitz_waterfall
--max-records N	(unset → cost gate fires)	When set and N >= record count, gate is skipped (caller pre-approved cost). When N < record count, skill stops and reports overflow — does NOT silently truncate.
--resume	(off)	Force resume from last completed phase based on output-dir file existence. Default behavior (no flag) auto-detects via Operational rule 2 file-existence check.

Source manifest + TAMConfig location

Both written to the resolved --output-dir:

• Nites/Supply path: docs/research/tam/{vertical}-{YYYY-MM-DD}/{manifest.json,tam-config.json}.
• Labs path: docs/campaigns/labs/tam/{slug}/{icp.json,tam-config.json}.

The skill writes; downstream consumers read.

Enrichment-provider selection

Read in priority order (per ADR-008 §Unset resolution order):

1. --enrichment-provider <id> flag if passed.
2. ${user_config.enrichment_provider} from plugin.json userConfig if explicitly set.
3. Auto-detect (when both above are unset):
   1. Check for brite-enrichment MCP registration in the active session → use brite_mcp.
   2. Else check for brite-enrichment CLI at $BRITE_DATA_PLATFORM/services/enrichment/cli.py → use brite_cli.
   3. Else fall through to blitz_waterfall.
4. skip is never auto-selected; it must be passed explicitly.

The resolved provider is logged at skill invocation so the user sees which path ran (e.g., [tam-mapping] enrichment_provider=blitz_waterfall (auto-detected; brite-enrichment MCP not registered, $BRITE_DATA_PLATFORM unset)). See the canonical 4-row enum table in §3 Phase 5 for per-value implementation and fallback messages.

Resume detection

Per Operational rule 2 (below), if --output-dir already exists with partial output, the skill detects the resume point via file existence in this stable order and continues from the next missing file:

1. manifest.json (Phase 1)
2. tam-config.json (Phase 2)
3. Per-source businesses.csv (Nites/Supply) OR companies.jsonl (Labs) (Phase 3)
4. crawled.jsonl (Labs only — Phase 3 spider sub-step)
5. all_sources_deduped.csv (Phase 4)
6. net_new_leads.csv (Nites/Supply) OR both excluded.jsonl AND companies-net-new.jsonl (Labs — both files required for Phase 4.5 to be considered complete) (Phase 4.5)
7. enriched.jsonl (Phase 5)
8. verified.jsonl (Labs only — Phase 6)
9. verified-flat.csv (Labs only — Phase 7 reshape; required by icp-scoring abc contract)
10. tier-{a,b,c}.csv + catch-all.csv (Labs only — Phase 7)

The skill NEVER restarts from Phase 1 when resume state exists. Stop the file-existence loop at the first missing file; do not check subsequent entries.

---

Methodology

Adapted from Revgrowth1/ai-gtm-workflows workflow 02 (MIT) for the 7-phase scaffolding, workflow 09 (MIT) for the Nites Phase 3 Google Maps ZIP method, and Revgrowth1/tam-map@9f5c72e74b (MIT) for the Labs-path 8-provider stack. Brite departures annotated inline as # Brite departure: .... See plugins/marketing/references/tam/UPSTREAM.md (BC-5946) for per-file port attribution.

Phase 1 — Source Discovery

Research every data source across 16 categories (literal taxonomy, in order):

1. Government / regulatory
2. Federal contracts (SAM.gov)
3. Industry associations
4. Manufacturer / vendor directories
5. Company databases (IcyPeas)
6. Local / maps
7. Review platforms
8. Social platforms
9. Business directories
10. Awards / rankings
11. Job boards
12. Events / conferences
13. Investor / funding
14. Open data
15. Marketplace / aggregator
16. Academic / research

Output: manifest.json listing every researched source with {name, type, url, category, est_record_count, access_method}.

Entity routing in this phase:

• Nites/Supply: Use the Revgrowth 02 taxonomy + plugins/marketing/references/research-processes/ (BC-5823) for source-discovery query templates.
• Labs: Adds AI Ark + Discolike + IcyPeas to the taxonomy (their MCPs feed directly into Phase 3 collection rather than producing a separate manifest entry).

Open-tracking-OFF reminder. Emit this verbatim string in Phase 1 output (sender-reputation rule):

OPEN-TRACKING DISABLED — sender-reputation rule, see §Brite Implementation → Architectural rules

Phase 1.5 — Keyword Expansion

Discover adjacent keywords sharing the same TAM. Primary keyword alone often misses 30–60% of market.

MANDATORY: Use IcyPeas free-count queries before pulling. Counts are free; pulls cost credits. Query each candidate keyword for total result count; rank by count and adjacency to the primary; commit only the top 5–10 to Phase 3 collection.

Cross-keyword dedup happens later in Phase 4 (Tier 1 domain match catches duplicate companies surfaced by multiple keywords). This phase only expands the keyword set.

Phase 2 — Config Generation

Build TAMConfig JSON from manifest.json. Schema:

{
  "vertical_name": "<string>",
  "entity": "brite-nites | brite-supply | brite-labs",
  "keywords": ["string", "..."],
  "naics_codes": ["6-digit-string", "..."],
  "sources": [
    { "name": "<string>", "type": "<string>", "config": { /* per-source */ } }
  ],
  "output_dir": "<string>",
  "enrichment_provider": "blitz_waterfall | brite_cli | brite_mcp | skip"
}

enrichment_provider reads from ${user_config.enrichment_provider} (ADR-008 §swap-path mechanics). The skill never hardcodes the value. Override via --enrichment-provider <id> flag.

Phase 3 — Collection (entity-routed)

Three sub-routes — pick the one matching entity:

3a. Nites residential — Google Maps ZIP scraping

(absorbs Revgrowth workflow 09)

• Tool: WebSearch (NOT Serper — cost reason; WebSearch is in allowed-tools).
• Query template: <keyword> "<city or ZIP>" per ZIP per priority.
• Initial implementation: 100–500 priority ZIPs per campaign (acceptable trade-off vs full 40K-ZIP traversal; split out if needed for scale).
• Output: {output_dir}/{source}/businesses.csv per source.

3b. Supply installer

• Tool: WebSearch + WebFetch for SAM.gov federal contracts, Houzz directory, state license databases.
• Query templates per source documented in plugins/marketing/references/research-processes/ (BC-5823).
• Output: same unified businesses.csv schema.

3c. Labs venue partnerships — 4-provider parallel discovery

Run in parallel; merge + dedup by domain at completion.

Provider	Tool	Script reference	Pagination
Spider.cloud	mcp__plugin_marketing_spider__*	plugins/marketing/scripts/tam-map/spider_crawl.py	crawls homepage + /about + /contact
AI Ark	mcp__plugin_marketing_aiark__*	plugins/marketing/scripts/tam-map/aiark_client.py + aiark-mcp.js	paginated, no stated rate limit
Discolike	mcp__plugin_marketing_discolike__*	plugins/marketing/scripts/tam-map/discolike_client.py + discolike-mcp.js	offset-based, X-Total-Count header
IcyPeas	Bash → python plugins/marketing/scripts/tam-map/icypeas_client.py --icp ./output/{slug}/icp.json	(no MCP — script-only per BC-5946)	max 100/page

Output:

• companies.jsonl — merged + deduped firmographic records.
• crawled.jsonl — Spider crawl results overlay (tech signals, summarized homepage content).

Unified businesses.csv schema (Nites/Supply)

Column	Type	Required	Notes
domain	string	yes	Normalized lowercase, www. stripped
company_name	string	yes	Free-text
state	string	yes	2-char US state code
address	string	no	Free-text
city	string	no
zip	string	no	5-digit
phone	string	no	Will be normalized in Phase 4
email	string	no	Optional pre-enrichment
industry	string	no
employees	integer	no
source	string	yes	Which scraper produced this row
source_url	string	no

Labs companies.jsonl schema

{ "domain": "...", "company_name": "...", "linkedin_url": "...", "geo": "...", "tech_signals": [...], "source": "spider|aiark|discolike|icypeas", ... }. Per-provider columns vary; the merger normalizes shared keys (domain, company_name, geo, source); provider-specific keys preserved as namespaced (spider_*, aiark_*, etc.).

Phase 4 — Dedup

3-tier algorithm (in order):

1. Tier 1 — domain match. Exact match on normalized domain (lowercase, strip www., strip trailing /).
2. Tier 2 — company name + state. Token-set Jaccard ≥ 0.85 on company name + exact state match. Catches DBA aliases.
3. Tier 3 — phone match. Normalized phone (strip non-digits, last 10 digits). Catches franchise locations sharing a phone tree.

Output:

• all_sources_deduped.csv — deduped TAM.
• dedup_stats.json — per-tier reduction counts:

  {
    "input_rows": 12300,
    "tier_1_domain_dedup_removed": 1200,
    "tier_2_name_state_dedup_removed": 450,
    "tier_3_phone_dedup_removed": 80,
    "output_rows": 10570
  }
  

Phase 4.5 — Exclusion (MANDATORY — never skipped)

Procedure mirrored by list-building § Workflow 2 (BC-2717) for its Sources 2 + 3 (dbt audience CSV, manual CSV) paths. Keep in sync — when one changes, audit the other.

HARD-FAIL rule. If either Email Bison workspace is unreachable (auth failure, network timeout after 3 retries, missing token), the skill HALTS and reports which workspace failed. Does NOT silent-skip and DOES NOT proceed to Phase 5. Reason: Phase 5 enrichment costs real money (BlitzAPI + Prospeo + MillionVerifier per-record); running it on already-contacted leads wastes credits.

Steps:

1. Availability checks (issue all 3 in parallel as a single tool-batch — ALL THREE MUST PASS — HARD-FAIL):
   • mcp__emailbison-b2b__get_active_workspace_info.
   • mcp__emailbison-personal__get_active_workspace_info.
   • mcp__plugin_marketing_salesforce__run_soql_query with SELECT Id FROM User LIMIT 1 (per plugins/marketing/tools/integrations/salesforce.md — get_username is NOT a valid liveness check).
2. Bulk pagination via mcp__emailbison-b2b__list_leads AND mcp__emailbison-personal__list_leads. Both workspaces.
3. Salesforce union query:

   SELECT Id, Email, Domain__c FROM Contact WHERE Domain__c IN (...)
   /* + */
   SELECT Id, Email, Domain__c FROM Lead WHERE Domain__c IN (...)
   

4. Merge into a domain-level exclusion set.
5. Filter all_sources_deduped.csv against exclusion set.

Output:

• Nites/Supply: net_new_leads.csv.
• Labs: excluded.jsonl (the rows that DID match exclusion are recorded for transparency; the surviving rows continue forward as companies.jsonl minus matches, written to a fresh companies-net-new.jsonl).
• Plus exclusion_stats.json:

  {
    "input_rows": 10570,
    "eb_b2b_excluded": 1900,
    "eb_personal_excluded": 320,
    "sf_contact_excluded": 850,
    "sf_lead_excluded": 280,
    "total_excluded": 3350,
    "output_rows": 7220,
    "exclusion_rate_pct": 31.7
  }
  

Typical exclusion rate: 20–40% (scoping doc cites 31.7% average).

Phase 5 — Enrichment Hand-off (pluggable)

Pluggable per ADR-008. Provider selection follows the resolution order in §Before Starting → Enrichment-provider selection.

enrichment_provider	Implementation	Status
blitz_waterfall	Shells to python plugins/marketing/scripts/tam-map/enrich_waterfall.py --in <input> --out enriched.jsonl (BlitzAPI 5 req/s serialized, Prospeo fallback max 20 workers)	Default. Production-ready.
brite_cli	Shells to services/enrichment/cli.py in brite-data-platform	Pending repo wiring; falls through to blitz_waterfall if repo missing locally
brite_mcp	Calls mcp__plugin_marketing_enrichment__* (brite-enrichment MCP)	Pending BC-5537/5538 GA. Currently NOT in allowed-tools; falls through to blitz_waterfall with pending BC-5537/5538 GA message
skip	No enrichment — pass through unenriched	Opt-in for testing or for handing off to BC-2717 list-building (which has its own enrichment pre-flight)

Pre-flight (all providers):

1. Email-verification credit check. Read MillionVerifier balance.
2. Volume-vs-budget cost estimate (Labs path uses BlitzAPI + Prospeo + MillionVerifier per-record costs):

   estimated enrichment cost: $X.XX for N records (BlitzAPI: $A, Prospeo: $B, MillionVerifier: $C)
   

   This verbatim string MUST appear in output before any enrichment call (grep test in evals).
3. Cost gate. Use AskUserQuestion to confirm BEFORE invocation if cost > $20 (configurable threshold per --max-records interaction; see §Before Starting).
4. API availability — read-only ping to each provider's auth endpoint.

Adaptive email waterfall (within blitz_waterfall):

• Sample 100–200 records. Run BlitzAPI → Prospeo waterfall on the sample. Measure hit rate.
• If sample hit rate < 30%, skill warns and asks user to confirm before committing the full waterfall.
• If sample hit rate ≥ 30%, proceed with the full list.

Post-enrichment verification:

• Keep records with verification status valid. Drop unknown, error, disposable, invalid.
• Output: enriched.jsonl.

Labs path note. The catch_all boolean flag is produced downstream in Phase 6 (SMTP verify), not here — Phase 5 has no source of catch-all signal. Nites/Supply paths terminate after Phase 5 without the catch-all distinction; their downstream consumers (BC-2717 / BC-5826) handle SMTP verify on their own schedule.

Pattern-based recovery anti-rule. Do NOT try info@<domain>, contact@<domain>, hello@<domain> for single-location businesses. Upstream tested 10 patterns × 15,934 domains = 0 hits. Single-location TAMs (Nites Google Maps, many Supply local installers, many Labs venues) almost never use generic mailboxes.

Entity routing exit:

• Nites/Supply: Phase 5 is the final phase. Hand off to list-building (BC-2717) when further enrichment needed, or directly to launch-campaign (BC-5826).
• Labs: Continue to Phase 6.

Phase 6 — SMTP Verify (Labs only)

Nites/Supply paths skip this phase. Downstream consumers (BC-2717 or BC-5826) handle SMTP verification.

• Tool: Bash → python plugins/marketing/scripts/tam-map/verify_smtp.py --in enriched.jsonl --out verified.jsonl.
• Throughput: 160 req/sec (MillionVerifier rate limit).
• Filter result codes:
  • Keep code 1 (valid).
  • Keep code 2 (catch_all) — but flag with catch_all=true so Phase 7 can route them to a separate output file.
  • Drop codes 3–6 (unknown, error, disposable, invalid).
• Output: verified.jsonl with explicit catch_all boolean column.

Catch-all isolation rule (non-negotiable). catch_all=true rows are kept in verified.jsonl so Phase 7 can route them to a separate output file. They are NEVER mixed into the tier-A/B/C CSVs. This is a user-explicit requirement for the tam-map port.

Phase 7 — Tier + Segment delegation (Labs only)

Delegates to icp-scoring (BC-5831) with --rubric abc. tam-mapping does NOT run a classifier itself.

Pre-tier filter — Operational rule 1 (No free-email providers in B2B output). BEFORE delegation, filter verified.jsonl rows whose email domain is one of gmail.com / yahoo.com / hotmail.com / outlook.com / icloud.com. Route them to personal-contacts.csv for manual outreach. NEVER include them in tier-A/B/C CSVs.

Reshape — JSONL → flat CSV with top-level catch_all (REQUIRED before delegation). Per icp-scoring's abc delegation contract (BC-5831 SKILL.md § "Tam-mapping delegation contract"), the caller (this skill) owns the JSONL→CSV reshape. verified.jsonl from Phase 6 nests the catch-all flag under record.smtp.catch_all; icp-scoring abc requires a flat CSV with a top-level catch_all column and stops with missing required column 'catch_all' for --rubric abc if absent. Before invoking the delegation call below, write verified-flat.csv with these columns: domain, company_name (if present), industry (if present), employees (if present), geography (if present), catch_all (boolean, flattened from smtp.catch_all). Free-email rows already routed to personal-contacts.csv in the prior step are excluded from verified-flat.csv.

Note on the two icp-scoring upstream feeders. verified-flat.csv (6 cols, this file) and list-building's enriched_leads.csv (16 cols, BC-2717) are deliberately different shapes. tam-mapping emits the tier-classification-only feeder (just what icp-scoring abc needs to score); list-building emits the fully-enriched feeder (also includes contact-level columns). Both satisfy icp-scoring's required column set; downstream consumers needing contact-level fields (e.g., launch-campaign's post-icp-scoring step) MUST consume from list-building's enriched_leads.csv, not from this verified-flat.csv.

Delegation call:

icp-scoring \
  --rubric abc \
  --max-records <N> \
  --output-dir docs/campaigns/labs/tam/{slug}/ \
  --criteria-file docs/campaigns/labs/tam/{slug}/icp.json

icp-scoring reads verified-flat.csv from --output-dir as input. Per icp-scoring's abc mode contract, the prompt template is read verbatim from plugins/marketing/references/tam/fit-scoring.md — not inlined here. When upstream tam-map updates the prompt, we re-port to fit-scoring.md and both skills inherit.

Returns:

• tier-a.csv — strong-fit prospects.
• tier-b.csv — secondary-fit prospects.
• tier-c.csv — weak/exploratory-fit prospects.
• catch-all.csv — catch_all=true rows scored separately (per icp-scoring abc mode contract).
• report.md — counts, drop reasons, top firmographic patterns.

The 4-CSV split is the contract launch-campaign (BC-5826) and list-building (BC-2717) consume.

---

Brite Implementation

Tools this skill calls

Organized by phase + reason:

What the skill needs to do	MCP server / tool	Repo or system	Reason (ADR / source)
Phase 3a Nites — scrape Google Maps ZIP	WebSearch	Public web	Revgrowth 09 + cost (no Serper)
Phase 3b Supply — federal contracts + dirs	WebSearch + WebFetch	SAM.gov, Houzz, state license dbs	Revgrowth 02
Phase 3c Labs — web crawl	mcp__plugin_marketing_spider__*	Spider.cloud	tam-map upstream; registered BC-5947
Phase 3c Labs — firmographic discovery	mcp__plugin_marketing_aiark__*	AI Ark	tam-map upstream; registered BC-5947
Phase 3c Labs — lookalike expansion	mcp__plugin_marketing_discolike__*	Discolike	tam-map upstream; registered BC-5947
Phase 3c Labs — keyword search	Bash → icypeas_client.py	IcyPeas	BC-5946 (script-only — no MCP wrapper)
Phase 4.5 — workspace 1 exclusion	mcp__emailbison-b2b__list_leads	Email Bison b2b workspace	ADR 2a (sole sequencer)
Phase 4.5 — workspace 2 exclusion	mcp__emailbison-personal__list_leads	Email Bison personal workspace	ADR 2a — two-workspace requirement (per BC-5832 scope)
Phase 4.5 — SF exclusion	mcp__plugin_marketing_salesforce__run_soql_query	brite-salesforce (production org)	ADR 2a (CRM SoR)
Phase 5 — enrichment (default)	Bash → enrich_waterfall.py	BlitzAPI + Prospeo	ADR-008 default blitz_waterfall
Phase 5 — enrichment (future swap)	mcp__plugin_marketing_enrichment__*	brite-enrichment	ADR-008 + BC-5537/5538 (NOT in allowed-tools until GA)
Phase 6 — SMTP verify (Labs)	Bash → verify_smtp.py

Architectural rules that apply

• MCP-cap exception ratified. Marketing plugin runs 4 plugin-level MCPs today (salesforce, spider, aiark, discolike) — within the ~5–6 advisory cap. Per BC-5945 §1, measurement methodology applies on each addition. Do not remove MCPs to "fix" perceived capacity issues; verify startup-latency < 2s and context-budget < 500 tokens deltas vs clean baseline before adding more.
• Open tracking OFF. Per upstream tam-map self-check #2: trackers trash sender reputation. Reminder emitted in Phase 1 output (verbatim string above).
• Phase 4.5 exclusion HARD-FAILS if either workspace unreachable. See §3 Phase 4.5 — never silent-skip; never single-workspace fallback.
• Catch-all isolation non-negotiable (Labs path). catch-all.csv is ALWAYS separate from tier-{a,b,c}.csv. User-explicit requirement.
• No free-email providers in B2B output (Operational rule 1; Labs path). Filter gmail / yahoo / hotmail / outlook / icloud before Phase 7 tier delegation.
• Incremental saves + resume from last completed phase (Operational rule 2). Each phase writes its output before advancing. Resume detects via file-existence in stable order.

Cross-skill boundaries

• Owns: TAM database construction. Source discovery. Keyword expansion. 3-tier dedup. Cross-workspace EB exclusion. Phase 5 hand-off orchestration. Entity-aware routing (Nites/Supply/Labs).
• Receives from: User invocation with --entity + --vertical. Optional gtm-strategy output for segment/ICP inputs.
• Hands off to (entity-specific):
  • Nites/Supply → list-building (BC-2717) when further enrichment needed, or directly to launch-campaign (BC-5826).
  • Labs → icp-scoring (BC-5831, Phase 7 delegation, --rubric abc) → launch-campaign (BC-5826) or list-building (BC-2717).
• Does not own:
  • Audience-view design in dbt → brite-data-platform.
  • Per-prospect enrichment beyond waterfall coverage → BC-2727.
  • List-to-campaign config → launch-campaign.
  • ICP scoring itself → delegated to icp-scoring.

---

MCP Tool Reference

Workflows grouped by phase, not by server. See plugins/marketing/tools/integrations/ for the integration guides per provider.

Workflow 1 — Phase 3 Labs collection (parallel discovery)

1. Availability checks (issue all 4 in parallel as a single tool-batch):
   • mcp__plugin_marketing_spider__spider_get_credits — confirms auth + balance.
   • AI Ark MCP liveness (lightest tool — see plugins/marketing/tools/integrations/ai-ark.md for the canonical liveness call).
   • Discolike MCP liveness (see plugins/marketing/tools/integrations/discolike.md).
   • IcyPeas: a free count query against a stub keyword (the script icypeas_client.py does not currently expose a dedicated healthcheck flag — see plugins/marketing/tools/integrations/icypeas.md for the canonical free-count probe shape; if missing, file a follow-up to add --healthcheck to the script).
2. On any failure, stop and report which provider failed.
3. Run all 4 providers in parallel against the keyword set from Phase 1.5.
4. Merge JSONL outputs; dedup by domain inline (Tier 1 only — full 3-tier dedup happens in Phase 4).

Workflow 2 — Phase 4.5 cross-workspace + SF exclusion

See §3 Phase 4.5 for the full step list (5 steps: 3-probe availability check, dual-workspace list_leads pagination, SF Contact + Lead union SOQL, merge + filter, write net_new_leads.csv or excluded.jsonl + exclusion_stats.json). This Workflow entry exists to confirm tool routing — the canonical procedure is in §3 Phase 4.5.

Workflow 3 — Phase 5 enrichment (provider-routed via Bash)

1. Resolve enrichment_provider per §Before Starting (priority: --enrichment-provider flag → ${user_config.enrichment_provider} → blitz_waterfall).
2. Switch on enum per §3 Phase 5 enum table. The table is the canonical source for each provider's invocation, fallback message, and status.
3. Cost gate before invocation (see §3 Phase 5 — verbatim string + AskUserQuestion if > $20).

Workflow 4 — Phase 6 SMTP verify (Labs)

1. Bash → python plugins/marketing/scripts/tam-map/verify_smtp.py --in enriched.jsonl --out verified.jsonl.
2. Filter result codes 1 + 2 (with explicit catch_all flag); drop 3–6.

Workflow 5 — Phase 7 tier delegation (Labs)

1. Pre-filter verified.jsonl for free-email domains → personal-contacts.csv (Operational rule 1).
2. Reshape remaining verified.jsonl rows to verified-flat.csv with a top-level catch_all column (flattened from smtp.catch_all). icp-scoring abc requires flat CSV with catch_all as a top-level column per its delegation contract (BC-5831).
3. Invoke icp-scoring skill with --rubric abc --max-records <N> --output-dir <slug-dir> --criteria-file <icp.json>.
4. icp-scoring reads verified-flat.csv and the prompt template at plugins/marketing/references/tam/fit-scoring.md (single source of truth).
5. Returns 4 CSVs + report.md.

MCP confirmation gates (out-of-scope reminders):

• Email Bison import_leads_to_campaign, resume_campaign, unsubscribe_lead, blacklist_lead, archive_campaign, enable_warmup, remove_email_from_blocklist, remove_domain_from_blocklist — these all have MCP-level confirmation gates per the Email Bison integration guide. tam-mapping does NOT call these (handed off to launch-campaign).
• IcyPeas paid find-companies is preceded by free count-companies per anti-slop rule 2.

---

Operational Runbook

Task 1 — Brite Nites residential TAM build

Preconditions:

• docs/marketing-context.md exists and identifies entity brite-nites.
• --vertical <slug> chosen (e.g., austin-municipalities).
• Output dir auto-derived: docs/research/tam/{vertical}-{YYYY-MM-DD}/.

Steps (Phases 1 → 5):

1. Phase 1 source discovery → manifest.json.
2. Phase 1.5 IcyPeas free-count keyword expansion.
3. Phase 2 TAMConfig generation (writes tam-config.json with enrichment_provider from userConfig).
4. Phase 3a Google Maps ZIP scraping via WebSearch → per-source businesses.csv.
5. Phase 4 dedup → all_sources_deduped.csv + dedup_stats.json.
6. Phase 4.5 exclusion (MANDATORY — both EB workspaces + SF) → net_new_leads.csv + exclusion_stats.json.
7. Phase 5 enrichment via resolved provider → enriched.jsonl (or --enrichment-provider skip to pass through).
8. Hand off to list-building (BC-2717) or directly to launch-campaign (BC-5826).

Expected output dir contents:

docs/research/tam/{vertical}-{YYYY-MM-DD}/
├── manifest.json
├── tam-config.json
├── {source}/businesses.csv     # one per Phase 3 scraper
├── all_sources_deduped.csv
├── dedup_stats.json
├── net_new_leads.csv
├── exclusion_stats.json
└── enriched.jsonl              # if Phase 5 ran

Error handling:

• Any MCP availability failure halts.
• EB workspace unreachable → HARD-FAIL with which workspace failed.
• Phase 5 cost > $20 without --max-records pre-approval → AskUserQuestion confirmation gate.

Task 2 — Brite Supply installer TAM build

Preconditions:

• marketing-context.md exists with brite-supply entity populated.
• --vertical <slug> chosen (e.g., landscape-installers-tx).

Steps: mirror Task 1 but Phase 3b uses SAM.gov + Houzz + state license databases (WebSearch + WebFetch) instead of Google Maps. Phases 4, 4.5, 5 unchanged.

Hand off to BC-2717 (typical for Supply because installer enrichment often needs further per-prospect work).

Task 3 — Brite Labs venue partnerships TAM build (full tam-map path, all 7 phases)

Preconditions:

• marketing-context.md exists with brite-labs entity populated.
• --vertical matches one of the 6 pre-loaded playbooks (zoos, aquariums, casinos, hotels-resorts, ski-resorts, sports-stadiums) OR user provides --criteria-file.
• Output dir auto-derived: docs/campaigns/labs/tam/{slug}/.
• BOTH EB workspaces must be reachable (HARD-FAIL otherwise).

Steps (Phases 1 → 7):

1. Phase 1 source discovery — Labs taxonomy adds AI Ark + Discolike + IcyPeas.
2. Phase 1.5 keyword expansion (IcyPeas free-count).
3. Phase 2 TAMConfig generation; lazy-load plugins/marketing/references/vertical-playbooks/{vertical}.md → write icp.json.
4. Phase 3c parallel discovery (Spider + AI Ark + Discolike + IcyPeas) → companies.jsonl + crawled.jsonl.
5. Phase 4 dedup → all_sources_deduped.csv (also kept as .jsonl for Labs continuity).
6. Phase 4.5 exclusion (MANDATORY) → excluded.jsonl + companies-net-new.jsonl.
7. Cost gate + Phase 5 enrichment → enriched.jsonl.
8. Phase 6 SMTP verify → verified.jsonl.
9. Free-email filter (Operational rule 1) → personal-contacts.csv separated.
10. JSONL→CSV reshape → verified-flat.csv with top-level catch_all column (per icp-scoring abc contract).
11. Phase 7 tier delegation to icp-scoring --rubric abc → tier-a.csv, tier-b.csv, tier-c.csv, catch-all.csv, report.md.
12. Hand off to launch-campaign (BC-5826) or list-building (BC-2717).

Expected output dir contents:

docs/campaigns/labs/tam/{slug}/
├── icp.json
├── tam-config.json
├── companies.jsonl
├── crawled.jsonl
├── all_sources_deduped.csv (or .jsonl)
├── excluded.jsonl
├── companies-net-new.jsonl
├── enriched.jsonl
├── verified.jsonl
├── personal-contacts.csv
├── verified-flat.csv
├── tier-a.csv
├── tier-b.csv
├── tier-c.csv
├── catch-all.csv
└── report.md

Task 4 — Resume an interrupted run

Preconditions:

• A previous run's output directory exists with partial output.

Steps:

1. Skill reads --output-dir and runs the file-existence check in stable order (see §Before Starting → Resume detection).
2. Resume from the first missing file's phase.
3. NEVER restart from Phase 1.
4. If --resume flag is passed, force resume even when state could be ambiguous (e.g., partial JSONL writes — the skill validates the last record line and resumes from the next).

Expected output: pipeline continues; no duplicate work; final output dir contents match Task 1/2/3 expectations for the active entity.

---

Health Scoring Rubric

Score	Criteria
10	Runs the entity-correct phase route end-to-end. Cites all 16 source categories in Phase 1 manifest. Phase 4.5 exclusion runs against BOTH EB workspaces + SF, HARD-FAILS on missing token. Cost gate fires before Phase 5. Open-tracking-OFF reminder emitted verbatim. Catch-all isolation enforced (Labs). Free-email filter applied (Labs). Resume detection works without restarting from Phase 1. References ADR-008 for enrichment pluggability. Cross-links to BC-2717 / BC-5826 / BC-5831 are present.
7-9	Same as 10 but skips one verification — e.g. forgets the open-tracking reminder, OR skips the cost gate, OR runs Phase 4.5 against only one EB workspace. Output is functional but missing one architectural rule.
4-6	Runs the phases but skips Phase 4.5 entirely OR mixes catch-all into tier CSVs OR uses pattern-based email recovery on single-location businesses OR restarts from Phase 1 on resume. Functional but violates a core rule.
1-3	Hallucinates source taxonomy. Calls unregistered MCP servers (e.g., mcp__plugin_marketing_enrichment__* before BC-5538 GA). Skips IcyPeas free-count and pulls credits blind. Outputs gmail/yahoo addresses in tier CSVs. Hard-fails silently.

---

Anti-Slop Guardrails

• Do not generate generic marketing jargon ("synergy", "leverage", "best-in-class").
• Do not fabricate statistics, case studies, or testimonials — always attribute to a source.
• Do not produce output that ignores docs/marketing-context.md.
• Do not recommend tools the plugin does not have access to (no hallucinated MCP servers, no assumed local clones).
• Always run Phase 4.5 exclusion against BOTH EB workspaces + SF. Never skip — costs real money to enrich already-contacted leads.
• Always run IcyPeas count queries before paid find-companies. Counts are free; pulls cost credits.
• Always emit unified businesses.csv schema from every Phase 3 Nites/Supply scraper (and the JSONL equivalent for Labs). Schema variance breaks Phase 4 dedup.
• Always dedup before enrichment. Never enrich a pre-dedup TAM.
• Never use pattern-based email recovery (info@, contact@, hello@) on single-location businesses. Upstream tested 10 patterns × 15,934 domains = 0 hits.
• Never mix catch-all rows into tier-A/B/C.csv (Labs path). catch-all.csv is ALWAYS a separate file. User-explicit requirement.
• Never include free-email-provider rows (gmail.com, yahoo.com, hotmail.com, outlook.com, icloud.com) in tier-A/B/C.csv (Labs path). Sender-reputation rule. Route to personal-contacts.csv instead.

---

Behavioral Tests

Tier 1 — Free assertions (5)

1. Given user invokes "build a TAM for Nites residential in the Austin metro", output must walk through Phases 1, 1.5, 2, 3, 4, 4.5, 5 and explicitly skip Phases 6 + 7 (Labs-only).
2. Given user invokes "build a Labs zoos TAM", output must walk all 7 phases and explicitly cite the lazy-load step plugins/marketing/references/vertical-playbooks/zoos.md.
3. Output sample tier-A/B/C rows must NOT contain free-email domains (gmail.com, yahoo.com, hotmail.com, outlook.com, icloud.com).
4. Given a vertical with no playbook (e.g., "build a Labs TAM for breweries"), output must accept --criteria-file or interactive ICP entry as fallback — NOT silently fail.
5. Given a resume scenario ("the last run died at Phase 5"), output must detect the resume point from file-existence and NOT restart from Phase 1.

Tier 2 — Tool-assisted (7)

6. If docs/marketing-context.md exists, output must reference Brite entity from that file in the Phase 1 manifest.
7. If mcp__emailbison-b2b__get_active_workspace_info returns auth failure, skill HARD-FAILS at Phase 4.5 — does NOT proceed to Phase 5.
8. If mcp__emailbison-personal__get_active_workspace_info returns auth failure (with b2b OK), skill STILL HARD-FAILS at Phase 4.5 — both must succeed.
9. If ${user_config.enrichment_provider} is brite_mcp and the MCP is unavailable, output emits "pending BC-5537/5538 GA" message and falls through to blitz_waterfall.
10. If ${user_config.enrichment_provider} is skip, Phase 5 short-circuits; downstream Phases 6+7 still run for Labs.
11. Open-tracking-OFF reminder appears as verbatim string OPEN-TRACKING DISABLED in Phase 1 output (grep test in evals).
12. Cost-estimate string estimated enrichment cost: appears in output before any Phase 5 enrichment call (grep test in evals).