Playbook Tech On Website

Playbook: Technology On Website

All rules here are best practice, not law. Override any of them when the campaign calls for it; note the best practice once and move on.

1. Trigger and scope

Use when: the offer only makes sense to companies running a specific piece of software on their site — a Shopify app, a Klaviyo migration, a HubSpot implementation, a WordPress maintenance offer. Works in both directions: discovery ("build me a list of every company on Shopify") and enrichment ("here are 4,000 domains, which run Klaviyo").

Do not use when: you want the software a company sells, or mail-infrastructure targeting.

Default output: tech_confirmed, tech_stack_verified (JSON array), tech_evidence, tech_checked_at. Abstain = false / [] / "". On request only: tech_on_website_line, 110 chars.

The sentence is opt-in. The job is the verdict: does this company run the technology, and how do we know. That is what a list gets gated on, and for most campaigns it is the entire deliverable. Write the clause only when the brief explicitly asks. Never let an unrequested sentence be the reason a row costs a model call.

The thing that makes this playbook necessary

A technographic database tells you what a crawler saw at some unstated point in the past, and it is wrong often enough to embarrass you.

In the graded test, 4 of the 10 companies a provider returned from its own Shopify filter were not on Shopify. Two were not ecommerce at all.

The homepage verifier is not a quality step. It is the gate. Nothing reaches copy without it. Plan for roughly 60% of a provider-sourced list to survive verification, so pull 1.7x what you need.

2. Run it: tandem discovery, then the gate

The two discovery lanes run IN TANDEM and the result is a union. Not a waterfall, not a choice.

Measured: two providers' first pages returned 74 domains and 60 domains with zero overlap. Whichever single provider you pick, you leave most of the market on the table.

Watch two things when you compare them:

• A contact-oriented provider returns contacts, so page it with a per-company cap of 1. Never compare its raw count to a company-oriented provider's company count.
• Both cap per filter combination (commonly 25,000 and 50,000). Shard by state or headcount band and let the union dedupe.

No cache. Recompute — it is cheap. Every source is free except the rendering proxy, which only touches rows flagged blocked, so re-verifying a domain a previous campaign saw costs one homepage GET.

# 1. TANDEM DISCOVERY. Both lanes, together.
discover-tech --provider a Shopify --all --out a.txt
discover-tech --provider b Shopify --all --out b.txt

# 1c. union + dedupe, printing the per-source overlap
union-domains a.txt b.txt --out domains.txt --provenance sources.csv

# 2. THE GATE
verify-tech-html domains.txt > verified.jsonl

# 3. rescue ONLY the blocked rows (metered, explicit confirm)
jq -r 'select(.blocked == true) | .domain' verified.jsonl > blocked.txt
proxy-rescue blocked.txt --confirm --max 500 > rescued.jsonl

# 4. merge: a rescued row replaces its blocked counterpart, one row per domain
jq -s -c 'group_by(.domain) | map(sort_by(.blocked) | .[0]) | .[]' \
  verified.jsonl rescued.jsonl > final.jsonl

# 5. put target_tech on every row
attach-row-context final.jsonl --target-tech Shopify > ready.jsonl

# 6. THE DEFAULT LAST STEP: the verdict. No model calls, no cost.
tech-verdict ready.jsonl > verdicts.jsonl

Stop there unless a sentence was requested. verdicts.jsonl is the deliverable.

3. The gate

A browser-UA homepage GET at concurrency 2, matching fingerprints over HTML and response headers. Two behaviors carry the whole playbook.

Blocked is a flag, never an inference

A bot wall is not an answer.

This is subtle and it bites: a common CDN matches on its own server: header, so a 403 used to come back as a successful fetch with a non-empty detection list — which reads downstream as "we looked and found nothing." A silent false abstain.

The verifier emits "blocked": true with a blocked_reason on HTTP 401/403/405/429/503, any other 4xx/5xx, a body under 2,000 bytes, or a transport error — and strips infrastructure and analytics hits out of the detection list.

Route on the flag, never on an empty list.

Platform hits are graded

A Shopify fingerprint fires on HTML-only strings like cdn.shopify.com and <store>.myshopify.com — which every Shopify agency portfolio, app-review roundup and Buy-Button B2B site also carries. So platform hits require header or oracle evidence:

Only Shopify and WordPress have oracles today, so an HTML-only match on any other platform stays unconfirmed by design. That costs recall and buys correctness.

Three outcomes that are NOT negatives

Getting this wrong is how a campaign quietly mails the wrong people.

target_tech is read per row, with a global default only. If neither is set, the script should error rather than grade everything against the wrong technology.

Adding a technology

Never write a fingerprint from memory. Learn it from a live sample: rank candidate strings by specificity (support ≥30%, leakage ≤5%) against a control set.

⚠️ The control set must control for the co-occurring platform, not just "any website". A Klaviyo sample surfaced cdn.shopify.com at 78% support / 0% leakage — because most Klaviyo users are Shopify stores. Control against Shopify stores, not against the open web.

Then: never add a bare vendor domain (/klaviyo\.com/ matches every page that links to them); prefer response headers; a platform-kind technology also needs an oracle; and pass a 3-positives / 3-negatives ritual before marking it validated.