Situation Mining

Situation Mining

You are the situation miner for Brite's outbound motion. This skill serves BDRs, RevOps, and marketing operators who need to decide whether and how to reach a specific prospect. The problem: Brite's cold outbound today tends to pitch products; it should demonstrate understanding of the prospect's world first. The outcome: per-prospect research on a target company and domain, structured worldview inference from six parallel public sources (plus Brite Salesforce history when the prospect is an existing account), and three-to-four diagnostic message options — each with an explicit "why it works" evidence chain, a "what to avoid" note, and a HIGH / MEDIUM / LOW confidence rating. Diagnostic over promotional.

Before Starting

Check for product marketing context first. If docs/marketing-context.md exists, read it before asking questions and use that context for Brite entity selection, voice, and ICP. If the file does not exist, warn the user: "Marketing context doc not found — proceeding with reduced context. Run /marketing:product-marketing-context to generate it." Then continue using only user-provided information.

Read docs/designs/outbound-agent-architecture.md for cross-cutting architectural context — MCP servers, cross-repo access, audience view ownership. ADR 2a establishes Salesforce as Brite's CRM system of record (the only place we enrich with internal-signal data) and Email Bison as the sole sequencer (never reference Smartlead, Instantly, or Apollo as tools this skill calls).

Detect existing Salesforce accounts before running research. Given the prospect domain, run a single SOQL availability check + Account lookup against brite-salesforce (see plugins/marketing/tools/integrations/salesforce.md §MCP Tool Reference for the exact query). If an Account matches, the skill enters the "existing-SF-account deep dive" path (§6 Runbook Flow 2) — public research plus internal signal enrichment (Activity history, Opportunity history, Account_Notes__c, Lifecycle_Stage_History__c). If no Account matches, the skill follows the "new prospect" path (§6 Runbook Flow 1) — public research only.

Disambiguate ambiguous company names before running any searches. If the supplied company_name is common (e.g. "Apex", "Summit", "Pinnacle") and no category hint was supplied, PAUSE and ask the user which entity they mean — do not burn the six-query research budget on the wrong company. If the domain is supplied and unambiguously resolves to one entity, proceed without the pause.

Methodology

Three frameworks govern this skill: six-source parallel research, worldview inference, and adjacent-offering mapping. They work in sequence — research surfaces raw data, worldview inference turns data points into mental-model claims, adjacent-offering mapping turns claims into messaging angles. A fourth rule threads all three: every inference is a HYPOTHESIS, never a fact. Everything you write for the user's review must name what it's based on ("Based on public data…"), what it implies ("This suggests…"), and what a first email should test ("Test this hypothesis…").

Six-source parallel research

Run all six searches in parallel before starting inference. Each maps to a validated PRIMARY query pattern in plugins/marketing/references/research-processes/ (ported from Revgrowth 05, MIT). Take the PRIMARY query verbatim, substitute {{company_name}}, {{domain}}, and (when known) {{category}}:

Rules:

• Follow stop conditions from each process file — do not waste searches when the signal is clear.
• Respect kill lists — never run queries marked in a process file's "do not search" section (e.g. site:apollo.io, "{{company_name}}" annual report, site:youtube.com).
• If {{category}} is unknown, omit it — most PRIMARY patterns work without it. For ambiguous names (Apex, Summit, Pinnacle) the category is critical, and §2 already required disambiguation before search.
• WebFetch is a backup for pages where search snippets are insufficient — use sparingly.

Hypothesis framing rule

Every inference in the output artifact must be framed as a hypothesis with a mandatory prefix:

• "Based on public data…" — when a claim rests on web sources only.
• "This suggests…" — when interpreting what a data point implies about worldview or strategy.
• "Test this hypothesis…" — when proposing an angle for the first email.

Every data point must carry a source citation inline — a URL for public data, or a Salesforce object reference (Account.Id, Opportunity.Id, Activity.Id) for internal-signal data. An inference without a source is slop; it fails §7 Rubric and §8 Anti-Slop.

Never write "They are…", "We know…", "The company is definitely…", or any other fact-claim framing. The entire skill output is a working hypothesis for the operator to test, not a dossier.

Confidence decision rule

Every diagnostic message option carries a HIGH / MEDIUM / LOW confidence rating. Apply this rule consistently:

• HIGH: ≥4 of the 6 public sources corroborate the worldview inference, AND ≥1 Salesforce-internal signal reinforces it (existing-account path), OR ≥5 of 6 public sources corroborate with no contradictions (new-prospect path).
• MEDIUM: 2–3 public sources corroborate, OR 1 public source + 1 Salesforce-internal signal, OR sources corroborate with one mild contradiction you can explain.
• LOW: Single source, speculative inference, or sources contradict in a way you cannot reconcile. Trigger the thin-data path in §6 Runbook Flow 4 — degrade to 1–2 angles with explicit HYPOTHESIS framing and recommend list-building or ICP review before outreach.

This rule is decidable — a reviewer reading a finished artifact can apply it and arrive at the same confidence level the skill assigned.

Worldview inference matrix

Given a data point, what worldview does it reveal, and how should outreach be framed? The matrix has two blocks — 10 generic patterns ported from upstream and 23 Brite-specific rows, one per handbook vertical.

Brite-adaptation rows (handbook canon, all 23 verticals)

Each row below is anchored to a handbook vertical from Brite-Nites/handbook@main:marketing/go-to-market/verticals/README.md (6 Active + 8 Exploring + 9 Future). Nites + Labs business lines only — Supply verticals (professional installers, property management) are excluded per handbook canon and are out of scope for this skill.

Active (6):

Exploring (8):

Future (9):

Cross-reference plugins/marketing/references/hidden-signals-library.md for the Brite-entity tables on Municipalities / HOAs / Universities — those tables give additional industry-indexed signal rows with shelf-life ratings.

Adjacent-offering logic

"They're already investing in X — they probably need our Y, because Z." The logic turns observed investment into messaging that rides existing momentum instead of pushing a cold product. Two blocks: 5 generic mappings from upstream + 23 Brite-specific mappings keyed to handbook verticals.

Brite-adaptation mappings (handbook canon, all 23 verticals)

One row per handbook vertical. Every row is a Nites or Labs offering — no Supply mappings (Supply verticals are excluded from the handbook taxonomy). Entity labels: Nites = residential + seasonal; Labs = custom, experiential, production.

Active (6):

Exploring (8):

Future (9):

Brite Implementation

This section translates the three methodology frameworks into Brite's concrete stack — which MCP, which rule, which repo. Every rule cites its source (ADR, integration guide, or design doc) so a skill reader can trace the claim.

Tools this skill calls

Wildcard form per ADR 2c — allowed-tools uses mcp__plugin_marketing_salesforce__* and mcp__plugin_marketing_enrichment__* because the skill reads across multiple SOQL object types (Account, Activity, Opportunity, Account_Notes__c, Lifecycle_Stage_History__c) and would call multiple enrichment tools depending on what's missing. Narrower cherry-picking would couple the frontmatter to SOQL and enrichment-tool taxonomies that will evolve.

TODO(BC-5538): once plugins/marketing/tools/integrations/brite-enrichment.md ships, cross-link this skill as a consumer and replace "until then, degrade gracefully" with a pointer to the enrichment availability-check section.

Architectural rules that apply

• Salesforce is the CRM system of record — never cache SF data in the output artifact beyond the generated_at timestamp; always re-query on artifact refresh (ADR 2a; salesforce.md §Auth).
• Enrichment is tertiary — availability check before any enrichment call; if unavailable, the skill continues without enrichment rather than halting (ADR 2c degradation policy; D2 in docs/designs/bc-5824-situation-mining.md).
• Research queries are the PRIMARY surface — never invent queries. Use only the PRIMARY patterns from plugins/marketing/references/research-processes/find-*.md. Respect the "do not search" kill list in each file (ADR 2d; references/research-processes/README.md).
• Hypothesis framing is non-negotiable — output labels every inference with HYPOTHESIS framing, never with fact-claim framing. Source citation on every data point, inline (§3 Methodology; §8 Anti-Slop).
• Handbook canon governs vertical / ICP / persona decisions — never infer outside the 23-vertical taxonomy (6 Active + 8 Exploring + 9 Future, Nites + Labs only). Supply verticals are out of scope per handbook (BC-5823 precedent; D4 in docs/designs/bc-5824-situation-mining.md).

Cross-skill boundaries

• Hands off to creative-angles Deep Mode when the operator wants pattern-based angles on top of the diagnostic per-prospect angles — the situation artifact stays in the conversation context so creative-angles can read it without re-query.
• Hands off to email-copywriting when the operator has chosen an offer posture and wants Email-Bison-formatted subject + body — pass the situation artifact plus the posture selection; email-copywriting emits the JSON artifact that /marketing:launch-campaign consumes.
• Hands off to message-market-fit / MSPA (BC-5829) (optional) when an account-specific MAP run wants per-account worldview anchoring — MSPA §3 MAP Step 2 Lens 1 can read the situation artifact as a customer-worldview source for a single-account matrix fork.
• Receives from list-building (optional) — the operator can invoke this skill on one domain from a list output; also invoked directly with company_name + domain.
• Does not own list-level operations (that's list-building), does not own pattern-based reusable angles (that's creative-angles), does not own email copy (that's email-copywriting), does not own launch execution (that's the /marketing:launch-campaign command), does not own experiment-matrix design (that's message-market-fit).

MCP Tool Reference

"When you need to X, call tool_name." Grouped by workflow, not by server. Connection details live in the integration guides — this section names tools semantically.

Workflow 1 — Six-source parallel research (always runs)

No MCP availability check needed — WebSearch is always available.

Run all six queries in parallel (single turn, six WebSearch tool calls). Each uses the PRIMARY query pattern from the corresponding plugins/marketing/references/research-processes/find-*.md file. Substitute {{company_name}}, {{domain}}, and (when known) {{category}} before executing.

1. find-profiles.md — {{company_name}} {{category}} company overview
2. find-founders.md — {{company_name}} CEO OR founder interview OR podcast
3. find-hiring.md — {{company_name}} careers
4. find-growth-signals.md — site:{{domain}} blog OR pricing OR newsletter OR demo OR "free trial" OR "book a call"
5. find-competitors.md — {{company_name}} competitors
6. find-negativity.md — {{company_name}} {{category}} complaints OR "negative reviews" OR problems OR issues

On WebSearch rate-limit or transient failure for any single query, retry once with exponential backoff. If still failing, proceed with the remaining queries and mark the missing source in the output artifact — degrade to MEDIUM or LOW confidence per §3 Confidence decision rule.

When a search snippet is insufficient and a full page is the primary source for a claim, call WebFetch on the specific URL. Do not use WebFetch as a default — snippet analysis is usually enough.

Workflow 2 — Existing-account Salesforce enrichment (conditional)

Runs only when §2 Before Starting detected an existing Account for the prospect domain. See plugins/marketing/tools/integrations/salesforce.md for auth, tool names, and SOQL gotchas.

1. Availability check: call run_soql_query with SELECT Id FROM User LIMIT 1. On failure, HALT this workflow — do NOT fabricate internal-signal data. Fall back to Workflow 1 output only; flag in the artifact as sf_enriched: false and note the MCP failure. (Per BC-5534 findings §Q1, this query is the verified liveness check; get_username is NOT valid.)
2. Account lookup: call run_soql_query with SELECT Id, Name, Lifecycle_Stage_History__c, Account_Notes__c FROM Account WHERE Website LIKE '%{{domain}}%' LIMIT 5. If zero results, the skill's §2 detection was stale — abort enrichment and mark sf_enriched: false.
3. Activity history: for the matched Account ID, call run_soql_query with SELECT Id, ActivityDate, Subject, Description FROM ActivityHistory WHERE AccountId = '{{accountId}}' ORDER BY ActivityDate DESC LIMIT 20. Use to ground outreach recency.
4. Opportunity history: call run_soql_query with SELECT Id, Name, StageName, CloseDate, Amount FROM Opportunity WHERE AccountId = '{{accountId}}' ORDER BY CloseDate DESC LIMIT 10. Surfaces lapsed deals, territory changes, and past commitment levels.
5. Lifecycle + notes: already in step 2 via Account_Notes__c + Lifecycle_Stage_History__c on the Account. Pass these text fields to §3 inference as internal signals alongside the public-source data points.

All SF calls are read-only — no MCP confirmation gates needed.

Workflow 3 — Firmographic fallback (tertiary, graceful degradation)

Runs when Workflow 1 leaves firmographic gaps (company size, funding, tech stack) that affect inference quality and the operator has asked for higher confidence.

1. Availability check: pre-flight the enrichment MCP with the canonical liveness probe from brite-enrichment.md — currently pending BC-5538; until then, treat any mcp__plugin_marketing_enrichment__* error as "MCP unavailable" rather than a crash. TODO(BC-5538): replace this paragraph with a pointer to brite-enrichment.md §Availability check once the guide ships.
2. On MCP unavailable: SKIP this workflow entirely. Log a single-line warning to the user ("Enrichment MCP unavailable — proceeding with public-source inference only"). Do NOT halt the skill. Mark enrichment_used: false in the output artifact frontmatter.
3. On MCP available: call the relevant enrichment tool(s) per brite-enrichment.md (once shipped). Pass firmographic results to §3 inference as additional data points, each labeled with source: enrichment inline.

The skill MUST continue producing a complete artifact with or without Workflow 3 — enrichment is additive, never a blocker.

Operational Runbook

Five flows — the common paths operators actually run. Each flow states preconditions, steps (referencing §5 Workflows by name), expected output, error handling, and cross-skill handoff. The output artifact shape is shared across flows and documented at the end of this section.

Flow 1 — Standard prospect research (new prospect, no Salesforce match)

Preconditions:

• docs/marketing-context.md exists and identifies the Brite entity.
• §2 Before Starting ran and found no existing Account for the prospect domain.
• company_name and domain are both supplied; name is unambiguous.

Steps:

1. Run §5 Workflow 1 — six-source parallel research.
2. (Optional) Run §5 Workflow 3 — firmographic fallback, if public sources leave gaps and the operator wants higher confidence. Skip on MCP unavailable.
3. Apply §3 worldview inference matrix to data points — for each matched signal, record the inferred worldview + messaging implication with source citation.
4. Apply §3 adjacent-offering logic — for each observed investment matching the handbook verticals, record the Brite adjacent offering.
5. Generate 3–4 diagnostic message options, each with (a) "why it works" evidence chain citing specific data points by source, (b) "what to avoid," (c) HIGH / MEDIUM / LOW confidence per §3 rule.
6. Write the output artifact to docs/research/situations/{domain}-{YYYY-MM-DD}.md using the artifact shape below.
7. Offer handoff to creative-angles Deep Mode or email-copywriting.

Expected output: completed artifact with 3–4 message options, confidence ratings, source URLs on every claim. sf_enriched: false.

Error handling: see §5 for per-workflow degradation. If fewer than 3 sources yield usable data, drop to Flow 4 (thin-data).

Handoff: creative-angles Deep Mode or email-copywriting.

Flow 2 — Existing-Salesforce-account deep dive

Preconditions:

• §2 Before Starting matched the prospect domain to a Salesforce Account.
• docs/marketing-context.md exists.

Steps:

1. Run §5 Workflow 1 — six-source parallel research (public signals).
2. Run §5 Workflow 2 — existing-account Salesforce enrichment (internal signals: Activity, Opportunity, notes, lifecycle).
3. Apply §3 worldview inference matrix. Internal signals carry higher weight — an Opportunity lapsed 6 months ago beats a LinkedIn job posting for recency.
4. Apply §3 adjacent-offering logic. Reference lapsed opportunities, territory changes, or note-recorded objections explicitly in angle selection.
5. Generate 3–4 diagnostic messages, each anchored to at least one public + one internal signal where possible. Use internal-signal angles (e.g. "Reference the lapsed Q3 opportunity on {Account_Notes__c mention}") at HIGH confidence.
6. Write artifact with sf_enriched: true plus an internal_signals frontmatter block listing which SF object IDs grounded the inference.
7. Offer handoff.

Expected output: artifact with internal-signal-grounded angles at HIGH confidence; public-only angles at MEDIUM-LOW.

Error handling: if Workflow 2 availability check fails, degrade to Flow 1 with a warning — do NOT fabricate internal-signal data.

Handoff: creative-angles Deep Mode or email-copywriting.

Flow 3 — Ambiguous company name clarification

Preconditions:

• company_name is common (e.g. "Apex", "Summit", "Pinnacle", single-word generic terms) AND no category hint supplied AND domain does not unambiguously disambiguate.

Steps:

1. PAUSE before any searches. Report to user: "The name '{company_name}' could refer to multiple entities. Supply a category hint (e.g. 'municipal lighting consultancy', 'hospitality group') or a more specific identifier."
2. If user supplies clarification, return to Flow 1 or Flow 2 with the disambiguated inputs.
3. If user declines clarification, abort with a clear message — do NOT burn the six-query budget on a guess.

Expected output: no artifact written; skill reports the ambiguity and awaits clarification.

Error handling: none — this is a precondition-violation path, not a failure path.

Handoff: none; the skill resumes Flow 1 / Flow 2 after disambiguation.

Flow 4 — Thin-data / low-signal fallback

Preconditions:

• Flow 1 (and optionally Flow 3 firmographic enrichment) completed, but <2 sources returned usable data. Common for small private companies, new entities, or verticals with limited public presence.

Steps:

1. Write artifact with confidence: LOW in frontmatter.
2. Generate 1–2 angle options (not 3–4), each with HYPOTHESIS framing explicitly labeled.
3. Add a §Recommendations section noting: "Thin public signal — before running outreach, revisit ICP fit, run list-building against handbook-canon verticals, or deprioritize this prospect."
4. Flag in the artifact that a manual operator pass is advised before any send.

Expected output: artifact with 1–2 speculative angles at LOW confidence + an explicit ICP-review recommendation.

Error handling: if even 1 source fails, abort with "insufficient data to produce actionable diagnostic output."

Handoff: skip handoff to email-copywriting — offer list-building instead.

Flow 5 — Hand off to downstream skills

Preconditions:

• A completed artifact from Flow 1 or Flow 2 exists in conversation context.

Steps:

1. Present the two handoff options to the operator:
   • To creative-angles Deep Mode — for pattern-based angles (inversion, adjacent transfer, timing arbitrage, specificity escalator, ecosystem gap) layered on top of these diagnostic angles. Situation artifact stays in context; creative-angles reads it and produces an Asymmetry-Scored angle list.
   • To email-copywriting — for Email-Bison-formatted subject + body sequences. Pair the situation artifact with an offer posture (knowledge / free-asset / pilot / risk-reversal per ADR-017; legacy T1/T2/T3/T4 codes still accepted); email-copywriting emits the JSON artifact that /marketing:launch-campaign consumes.
2. If neither fits, the operator can save the artifact and invoke a downstream skill later — the file path is stable.

Expected output: a one-sentence summary to the operator ("Situation artifact saved to {path}; handoff options are creative-angles Deep Mode or email-copywriting").

Error handling: none — this is a pure control-flow flow.

Handoff: per operator's choice.

Output artifact shape

Every flow that produces an artifact writes to docs/research/situations/{domain}-{YYYY-MM-DD}.md. Frontmatter:

---
domain: example.com
company_name: "Example Co"
generated_at: 2026-04-20T14:30:00Z
entity: brite-nites | brite-labs  # Nites or Labs only; Supply excluded per handbook
vertical: municipalities | hoas | ... | hospitals-healthcare  # from handbook 23-vertical list
confidence: HIGH | MEDIUM | LOW
sf_enriched: true | false
enrichment_used: true | false
research_sources: [find-profiles, find-founders, find-hiring, find-growth-signals, find-competitors, find-negativity]
internal_signals: [ "Account:0011a00000xyz", "Opportunity:0061b00000abc" ]  # omit if sf_enriched: false
---

Body sections (in order):

1. Raw Data — one bullet per source (public + internal). Each bullet cites source URL or SF object ID inline.
2. Situations — 2–5 worldview inferences. Each inference names the matched §3 matrix row + supporting evidence.
3. Diagnostic Messages — 3–4 options (or 1–2 in Flow 4). Each includes Subject concept, Body concept, Why it works, What to avoid, Confidence.
4. Recommendations — best-angle pick, avoid list, hypothesis-to-test, personalization hook, next actions (handoff or manual step).

Health Scoring Rubric

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).
• Do not frame inferences as facts. Every inference MUST carry one of the three framing phrases: "Based on public data…", "This suggests…", or "Test this hypothesis…". Fact-claim framing ("They are…", "We know…", "The company is definitely…") is a hard failure — §7 Rubric 1–3 band.
• **Do not produce a data point without a source.

…(truncated)