# Signals

<!-- BEGIN GENERATED: guide-map -->
## Guide map

Read only the section needed for the next decision. Line ranges are exact
for this generated runtime target.

| Section | What it covers | Lines |
| --- | --- | --- |
| [Purpose](#purpose) | Scope, ownership, and the central operating question. | 27-31 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 32-36 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 37-46 |
| [Choose A Path](#choose-a-path) | Decision hierarchy for selecting the right capability or provider. | 47-61 |
| [Primary SDK Paths](#primary-sdk-paths) | Operating guidance and contracts for this section. | 62-72 |
| [Supporting References](#supporting-references) | Capability, provider, policy, and runtime guides for this outcome. | 73-84 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 85-98 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 99-109 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 110-118 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 119-130 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 131-142 |
| [Verification](#verification) | Evidence required before reporting success. | 143-150 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 151-160 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 161-170 |
<!-- END GENERATED: guide-map -->

## Purpose

Find timely evidence that can change GTM prioritization, such as funding, hiring,
activity, intent, or relationship signals.

## Use This When

Use this guide when the user asks why an account or person matters now. Do not
confuse GTM evidence with Slack notification rules.

## Do Not Use This For

| Need | Owning Guide |
| --- | --- |
| Configure or test Slack notification rules | `notifications.md` |
| Discover companies or contacts without a why-now predicate | `company-search.md` or `contact-search.md` |
| Enrich stable company or contact attributes | `company-enrichment.md` or `contact-enrichment.md` |
| Infer urgency from missing or stale evidence | Stop and report the evidence gap |
| Send, stage, or publish an action based on the signal | The relevant outbound, LinkedIn, inbox, or safety guide |

## Choose A Path

1. Define the signal predicate, observation window, entity, and expiry rule.
2. Use `funding.md` for structured funding-window evidence and
   `job-search.md` for current hiring evidence.
3. Use `linkedin.md` for current relationship or LinkedIn activity evidence,
   `web-research.md` for launches, news, public activity, or explicit pages,
   and `sources.md` when the signal already belongs to a typed source contract.
4. Keep the observed fact separate from the interpretation and recommended
   action.

Never query every signal source by default. Choose the source that directly
owns the claimed event, then corroborate only when the qualification predicate
requires it.

## Primary SDK Paths

<!-- BEGIN GENERATED: primary-sdk-paths -->
| Primary function | Choose it when | Required inputs | Returns | Exact contract |
| --- | --- | --- | --- | --- |
| `vf.funding.discover_companies` | Use a recent funding round as the why-now signal and preserve round facts as evidence. | `funding_after` | `funding_discovery_page` | [`funding.md`](funding.md) · installed SDK: `verbiflow/funding.py:87-188` |
| `vf.linkedin.search_posts` | Use recent LinkedIn posts or activity as the signal, with author, company, keyword, and freshness bounds. | None | `linkedin_posts` | [`linkedin.md`](linkedin.md) · installed SDK: `verbiflow/linkedin.py:191-208` |
| `vf.linkedin.get_contact_relationship` | Use when the why-now signal is the current sender-to-contact LinkedIn relationship rather than public activity. | `linkedin_url_or_slug` | `linkedin_relationship` | [`linkedin.md`](linkedin.md) · installed SDK: `verbiflow/linkedin.py:431-450` |
| `vf.web.search_start` | Use public-web evidence for signals not covered by a structured source, with an explicit freshness and qualification rule. | `queries` | `pending_artifact_job` | [`web.md`](web.md) · installed SDK: `verbiflow/web.py:16-85` |
<!-- END GENERATED: primary-sdk-paths -->

## Supporting References

Open only the child that resolves the next material decision.

| Reference | Use it for | Kind |
| --- | --- | --- |
| [`funding.md`](funding.md) | Recent structured funding discovery and qualification. | capability |
| [`web.md`](web.md) | Public web search, page extraction, screenshots, Markdown, and browser evidence. | capability |
| [`crunchbase.md`](crunchbase.md) | Crunchbase filters, entity resolution, count-first execution, pagination, and provider limits. | provider |
| [`linkedin.md`](linkedin.md) | LinkedIn reads, search, activity, conversations, messages, connections, and posts. | provider |
| [`sources.md`](sources.md) | Classify ambiguous source-shaped work and choose the owning acquisition surface. | policy |

## Mental Model

A signal has three layers:

| Layer | Meaning |
| --- | --- |
| Observation | A sourced event or state with an entity and time. |
| Qualification | The explicit rule that decides whether the observation matters now. |
| Interpretation | The reasoned implication and recommended action, labeled separately from fact. |

The same observation may qualify one GTM motion and not another. A signal also
expires. Preserve its observation window and expiry rule instead of turning a
historical fact into permanent urgency.

## Preflight

1. Define the entity, signal type, observation window, qualification threshold,
   expiry rule, required evidence, and intended decision.
2. Choose the source that directly owns the event. Do not fan out across every
   signal source.
3. Decide whether corroboration is mandatory and what contradiction would
   disqualify the signal.
4. Separate research from any downstream notification, prioritization, or
   outbound mutation.

## Risk And Side Effects

| Stage | Risk | Rule |
| --- | --- | --- |
| Inspect source evidence | Read or bounded provider work | Preserve entity, event time, source, and observation time. |
| Corroborate another source | Added cost, latency, and possible conflict | Do it only when required by the qualification rule. |
| Score or prioritize entities | Business-decision effect | Keep observed facts and interpretation visible and independently reviewable. |
| Notify, stage, message, or send | Customer-visible mutation | Leave for the owning activation guide and its approval boundary. |

## Canonical Operating Pattern

1. Record the signal predicate, decision it should inform, and expiry rule.
2. Acquire the most direct source evidence with a bounded window.
3. Resolve entity identity and normalize event time before qualification.
4. Apply the qualification rule, preserve rejected reasons, and corroborate only
   when the rule requires it.
5. Write the observed fact, interpretation, confidence, limitation, and suggested
   action as distinct fields.
6. Materialize the signal rows before handing them to notification, reporting,
   or outbound owners.

## Data Contracts

Each signal row should retain:

- stable entity identity and signal type;
- observed fact, event time, observation time, source, and source receipt or URL;
- qualification decision, threshold, and reason;
- expiry time or freshness status;
- interpretation, confidence, contradiction, and limitation fields separate
  from the observed fact;
- recommended next action without implying that the action was executed.

## Verification

Verify entity identity, event time, source, freshness, and the exact rule that
qualified the signal. Label inference as inference.

Inspect accepted, rejected, expired, and contradictory examples before claiming
coverage or prioritization quality.

## Troubleshooting

| Symptom | Likely Cause | Next Step |
| --- | --- | --- |
| Every account appears to have a signal | The qualification rule is too broad or source membership is treated as qualification. | Reapply threshold, window, and expiry rules to accepted and rejected samples. |
| A signal has no clear date | Event time and observation time were conflated. | Preserve both; mark event freshness unknown if the source cannot establish it. |
| Sources disagree | Corroboration produced conflicting entity or event facts. | Preserve both receipts, resolve identity, and downgrade or reject the signal explicitly. |
| The result contains recommendations but no evidence | Interpretation replaced the observation layer. | Rebuild each row from a sourced fact before retaining a recommendation. |
| A Slack rule was created during research | Signal research and notification delivery were conflated. | Stop activation and route notification work through `notifications.md`. |

## Related References

| Signal Type Or Next Decision | Read |
| --- | --- |
| Structured funding-window evidence | `funding.md` |
| Current hiring evidence | `job-search.md` |
| LinkedIn activity or relationship evidence | `linkedin.md` |
| Launch, news, or explicit public-page evidence | `web-research.md` |
| Typed acquisition source semantics | `sources.md` |
| Deliver a qualified signal to Slack | `notifications.md` |
