Merge variable render check

---
name: merge-variable-render-check
description: Checks that every merge variable in a cold email (subject, body, signature) matches a column in the lead file with the exact name and casing, finds empty and junk values that will render badly, and renders the template for real leads before activation. Catches the classic "Hi there" at scale caused by camelCase vs snake_case mismatches, job titles in the company column, N/A values and ALL CAPS names. Use when the user is about to upload leads or activate a campaign, pastes a template plus a CSV header or sample rows, or sees wrong names or raw {{tags}} in sent emails.
---

# Merge variable render check

You make sure the email each lead receives reads correctly. You compare the template's variables with the lead file, clean the values that will render badly, and show real renders before the campaign starts.

## Step 1. Collect inputs

Ask for:

- Every subject, body and signature in the sequence, as entered in the tool.
- The lead file header row and 20 or more sample rows (or the whole file).
- The sending tool, and how leads get in (CSV upload, API, integration).

## Step 2. Match variables to columns (ERROR)

1. List every `{{variable}}` in subjects, bodies and signature.
2. For each, find the column with the **exact** name. `firstName`, `first_name` and `FirstName` are three different fields. Many importers and APIs silently drop fields whose name does not match what they expect, so a whole campaign renders the fallback ("Hi there") or an empty string.
3. Check which naming the import path expects. A tool's CSV upload and its API can expect different casing. If unknown, test with one lead (step 4).
4. Variables the tool fills from the sending mailbox (sender first name, signature) are allowed without a column. They are often empty in the preview and filled at send time; that is normal.
5. Any variable with no column and no sender source is an ERROR.

## Step 3. Check the values (ERROR / WARN)

Scan every row used by a variable:

- ERROR: empty value where the template has no fallback. Suppress those leads or add a fallback.
- ERROR: junk values: `N/A`, `-`, `null`, `test`, a job title or number in the company column, an email address in the name column.
- WARN: ALL CAPS or all lowercase names and companies. Convert to title case, keeping known acronyms.
- WARN: legal suffixes in company names (`Inc.`, `LLC`, `Ltd`, `GmbH`). Strip them for the email: "Northwind" reads better than "NORTHWIND IT SERVICES LLC".
- WARN: first name that is an initial or includes a title ("Dr. J.").
- WARN: encoding errors (`Müller`), stray spaces, emojis.

Fix values before import. Many sequencers cannot edit a contact after import, so a fix after upload means delete and re-upload.

## Step 4. Render real leads

Pick 5 real rows: 3 typical, 1 with the most empty fields, 1 with the longest values. Render subject and body for each exactly as the tool will (resolve spintax on one path). Show them. Check subjects as well as bodies: subject bugs are the ones readers see first.

Then ask the user to upload those 5 leads to a test copy of the campaign, send to a mailbox they own, and compare with your renders. The tool's actual sent email is the ground truth; its preview screen may differ.

## Output format

1. Variable map: variable, column found, match (exact / case mismatch / missing), fill rate.
2. Value problems: column, issue, count of rows, fix.
3. Cleaned sample rows.
4. Five renders.
5. Go / no-go line.

## Rules

- Never activate on a template whose renders you have not read.
- A fallback like "there" hides a data problem. Report the fill rate of each field so the user sees how many leads get the fallback.

## Example

Input: template `Hi {{firstName}}, ... {{companyName}}`, CSV header `first_name,last_name,company,email`.

Output: `firstName` not found (column is `first_name`: case mismatch, will render empty or the fallback for every lead). `companyName` not found (column is `company`). 14 of 500 rows have `company` = "Owner" (job title): suppress or fix. Rename the template variables to `{{first_name}}` and `{{company}}`, or rename the columns, then render 5 leads.