/playbook-tech-on-website

name: playbook-tech-on-website
description: Decides which named technologies a company actually runs on its website, verified against the live site. Triggers on "find companies using Shopify", "they're on HubSpot", "tech stack targeting", "technographics", "who uses Klaviyo", "companies running WordPress". Outputs a per-domain verdict (tech_confirmed plus the verified stack and its evidence); the copy-ready clause is OFF by default and runs only when the operator asks for one.

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:

| Evidence | Grade | Result | |---|---|---| | response header (`x-shopid`, `x-shopify-stage`, `powered-by: shopify`) | **confirmed** | eligible for a clause | | a technology oracle answered yes (`/products.json`, `/wp-json/`) | **confirmed** | eligible for a clause | | HTML string only, no header, no oracle | **unconfirmed** | excluded from the stack, no clause |

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.

| `confidence` | Meaning | Action | |---|---|---| | `blocked` | **the page was never read** | proxy rescue. **Never a negative** | | `unconfirmed` | matched HTM