claude-skill

Run governed CRM hygiene through the HubSpot Agent CLI

Difficulty

advanced

Setup time

60-90 min

For

revops · gtm-engineer

RevOps

Stack

A Claude Skill that drives the HubSpot Agent CLI through bulk CRM hygiene — deduplication, property backfill, and stale-deal closure — under a written policy, producing a reviewable change ledger and a pre-image snapshot before any irreversible write. The bundle ships at apps/web/public/artifacts/hubspot-agent-cli-crm-cleanup-skill/ and contains SKILL.md plus three reference files you fill in before the first run.

Start with the part most pages would bury: HubSpot already ships free skills that do the mechanical work here. npx skills add hubspot/agent-cli-skills installs 15 skills, including bulk-operations (JSONL pipes, batch reads, pagination, dry-run/confirm patterns, hubspot history recovery), crm-data-quality (find incomplete records, normalize values, dedupe via objects merge), and deal-management (find stalled deals, close them). Install those first. This Skill does not replace them and does not reimplement them.

What the vendor bundle does not ship is policy. It gives you the idioms for merging records; it does not decide which duplicate wins field by field, where a backfilled value came from, when a quiet deal is dead rather than slow, or what evidence of the run survives afterward. That gap is the whole reason this Skill exists, and it is the gap that matters the moment a hygiene job runs headless on a schedule against a portal you do not personally own.

When to use

Use this when a HubSpot hygiene job has to satisfy at least one of four conditions: it runs on a schedule with nobody watching each mutation; somebody other than the operator reviews what changed; the touched properties feed routing, scoring, reporting, or comp, so a bad write has downstream cost; or the working set exceeds roughly 200 records, where pair-by-pair review stops being realistic.

The HubSpot Agent CLI entered public beta on 2026-06-23 as a binary separate from the hs developer CLI. Install it with curl -fsSL https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.sh | sh on POSIX, or the PowerShell equivalent on Windows, then authenticate with hubspot auth login. Commands follow a hubspot <noun> <verb> shape, output JSONL by default, and accept a global --dry-run that previews changes without applying them.

When NOT to use

A one-off cleanup in a portal you own. The vendor’s crm-data-quality skill does it with far less setup. Policy files are overhead when the operator is also the reviewer and the run happens once.
You cannot write a snapshot to disk. Merges cannot be undone. Without a pre-image there is no reconstruction path, and the Skill hard-stops rather than proceed.
The survivorship rule has not been decided. The Skill applies a rule you supply and refuses to invent one. An unfilled references/1-survivorship-policy.md is a stop, not a default.
Fewer than 50 records. HubSpot’s in-app duplicate manager plus manual review beats the setup cost at that size.
You want one run to do all three jobs. Dedupe, backfill, and stale-deal disposition each take a separate run against a separate policy file. Combining them produces a ledger no reviewer can read.

Setup

Budget 60-90 minutes, most of it spent filling policy files rather than installing anything. The survivorship argument — which record wins, and which fields survive from the loser — takes longer and happens before setup.

Install the CLI and the vendor skills. Run the install script, then hubspot auth login, then hubspot whoami to confirm the portal. Add npx skills add hubspot/agent-cli-skills. Claude Cowork users on Team or Enterprise accounts need an admin to allowlist api.hubapi.com first.
Install this Skill. Copy SKILL.md and the references/ folder into .claude/skills/hubspot-crm-hygiene/. The frontmatter name and description are what trigger it on a relevant prompt.
Create the two provenance properties. hygiene_source and hygiene_run_id, single-line text, on every object type you plan to backfill. Definitions are in references/2-backfill-provenance.md. The Skill stops if they do not exist.
Fill references/1-survivorship-policy.md. Match rules in Part A, primary selection in Part B, the field-level winner table in Part C, and the never-touch list in Part D. Attribution and consent fields belong in Part D — rewriting first-touch attribution during a cleanup rewrites marketing history invisibly.
Fill references/3-stale-deal-disposition.md with the pipeline owner in the room. Set each stage threshold at roughly twice that stage’s median duration from your own closed-won history.
Audit workflow enrollment triggers. List active workflows whose triggers reference any target property. This step is not optional; see the fourth failure mode.
Dry-run against a 200-record scope. Read ledger/digest.md end to end and confirm the ambiguous list looks like genuine judgment calls rather than a miscalibrated match rule.

What the skill actually does

Six phases, fixed order, no skipping forward.

Phase 1 pins the environment. It records hubspot --version and the authenticated identity into ledger/run-meta.json. HubSpot states that the beta’s commands, flags, and behavior can change without notice, so the version that produced a ledger is part of the ledger. Discovery runs under OAuth rather than a service key, because OAuth is scoped to the operator’s own permissions and a scoping mistake fails closed.

Phase 2 snapshots. Every record in scope is written to pre-image/<object_type>.jsonl before anything else happens. The reason is specific: --dry-run previews a write you have not made, and hubspot history restores property values on a record that still exists. Neither helps after a merge, because HubSpot documents no unmerge path and the losing record stops existing. Phase 5 refuses to run if the snapshot is missing or its line count does not match the working set.

Phase 3 generates candidates deterministically. Normalization and match rules run as code — no model judgment. A model asked to re-group the same duplicate set twice will not return the same grouping twice, which makes the diff between runs unreviewable and a reviewer’s sign-off meaningless. Model judgment appears in exactly one place, the ambiguous band, where its output is advisory and never auto-applied.

Phase 4 resolves under policy, per field rather than per record. This phase exists because of one HubSpot behavior: objects merge keeps the primary’s value wherever both records hold one. Picking a primary therefore discards good data on the secondary — the newer phone number, the corrected title, the populated lifecycle stage. So the Skill inverts the order. It pre-writes winning field values onto the primary with objects update, then merges, so the merge only folds associations and activity history. Groups the policy cannot resolve go to ambiguous.jsonl and are excluded from apply.

Phase 5 builds the ledger. Every planned mutation is issued with --dry-run --format json and folded into ledger/changes.jsonl — one line per record with before/after values and the rule that authorized the change — plus a human-readable ledger/digest.md. If any mutation class exceeds max_mutations (default 250) the run aborts and writes nothing. It does not truncate to the cap, because a half-applied hygiene run leaves the portal in a state worse than either endpoint.

Phase 6 applies, gated. Mutations replay from the ledger rather than from a freshly recomputed plan, so what executes is the artifact that was reviewed. Failures quarantine to failed.jsonl and are never blind-retried. Afterward every touched record is re-read into ledger/verified.jsonl.

Cost and throughput reality

The binding constraint is HubSpot’s API limits, not tokens.

Discovery runs against the CRM Search API, which is capped at 5 requests per second per account, returns at most 200 objects per page, and hard-caps at 10,000 total results per query — paging past that returns a 400. A 12,000-contact working set therefore has to be sharded by createdate into at least two queries. At 200 records per page and 5 requests per second, discovery reads about 1,000 records per second, so a 50,000-record scope takes roughly a minute of wall time.

Writes are bounded by the burst ceiling: 190 requests per 10 seconds for Professional and Enterprise private apps, 100 for Free and Starter, 250 with the API Limit Increase add-on. Daily ceilings are 625,000 calls on Professional and 1,000,000 on Enterprise. A 600-group dedupe run costs roughly 1,850 write calls — one survivorship pre-write per affected record plus one merge per group — which lands near 100 seconds of pure API time on Professional and consumes about 0.3% of the daily allowance.

Token cost is small by design, because matching is deterministic. Only the ambiguous band reaches the model, and at 30-60 groups per 10,000 records with roughly 800 input tokens per group, a full run costs well under a dollar in Claude tokens. The real cost is the 60-90 minute policy session, and it is a one-time cost amortized across every later run.

Success metric

Track duplicate creation rate, not duplicates removed. Removed duplicates measure how dirty the portal was; creation rate measures whether the intake path that made them has been fixed. Run the dedupe job monthly and chart new duplicate groups per 1,000 records created. A flat or rising line means form dedupe settings, list imports, or an integration are still producing collisions, and no amount of cleanup will outrun that.

The secondary metric is ambiguous-band size. It should shrink as the match rules get tuned. A band that stays above 10% of candidate groups means a rule in Part A is miscalibrated.

For stale deals, the calibration signal is the reopen rate during the notification hold. Above 15% means thresholds are too aggressive; raise them rather than arguing individual deals.

Failure modes

A merge is irreversible, and --dry-run does not change that. The preview shows the intended result without creating a restore point. HubSpot provides no unmerge. Guard: the Phase 2 pre-image is mandatory and Phase 5 hard-fails without it. Retain run_dir for at least a renewal cycle — it is the only path back for a record that no longer exists.
Merges fail at the 250-merge lifetime cap. HubSpot blocks a merge once two records have been involved in 250 or more merges combined, and a merge also fails when the result would exceed configured association limits. On a portal with years of cleanup history these failures cluster mid-run. Guard: failures quarantine to failed.jsonl with the API error attached and stop that group only. No blind retry — the same call fails identically, and retrying against a partially applied merge is how a cleanup becomes an incident.
Property writes fire workflow enrollment triggers. A lifecycle-stage backfill across 4,000 contacts can enroll all 4,000 in a nurture sequence and send 4,000 emails to existing customers. This is the largest blast radius on the page and it originates outside the CLI entirely. Guard: enumerate active workflows whose enrollment triggers reference the target properties, then pause them or exclude the working set for the run. The Skill prints the target property list at Phase 4 and requires explicit confirmation that the audit happened.
A backfilled value is indistinguishable from a human-entered one. Months later nobody can tell which records the job touched, so nobody can roll it back or exclude it from an analysis. Guard: every backfill write sets hygiene_source and hygiene_run_id on the same objects update call — not in a second pass, which leaves a crash window of stamped-but-unwritten records. The rollback procedure in references/2-backfill-provenance.md keys on the run id and restores only the properties the ledger names, so human edits made since the run survive.
Admin mode reaches past your own permissions. HubSpot requires a HUBSPOT_ACCESS_TOKEN service key for schema operations and most deletes, and that key is account-level. Exported into a long-lived shell it stays live for every later command. Guard: run discovery and dry-run under OAuth, and export the service key inside a subshell scoped to the single command that needs it.
Beta drift breaks a pinned run silently. The CLI auto-upgrades by default and HubSpot warns that flags can change without notice, so a flag that disappears between two scheduled runs turns a governed run into an ungoverned one. Guard: set HUBSPOT_NO_AUTO_UPGRADE=1 for scheduled runs, pin the version in run-meta.json, and treat a version delta as a review trigger.

vs alternatives

vs HubSpot’s official skills alone. They are free, vendor-maintained, and track the CLI as it changes — real advantages this bundle does not have. Use them alone when the CRM owner is running a one-time cleanup and reviewing results directly. Add this layer when the run repeats, when a reviewer is not the operator, or when someone will ask in six months which job wrote a value. The honest split: the vendor gives you the verbs, this gives you the policy and the receipt.

vs Insycle and similar dedupe SaaS. Purpose-built tooling has a real edge here — a non-technical ops owner can drive template-based bulk merges from a UI, and Insycle documents a merge-revert path that HubSpot itself does not offer. Buy that when the person running hygiene is not comfortable in a terminal and the budget exists. This Skill wins when hygiene runs headless on a schedule inside an agent, and when the policy needs to live in version control beside the rest of your ops configuration where a diff shows who changed the survivorship rule.

vs HubSpot’s in-app duplicate management. It is free and needs no setup, and it surfaces suggested duplicates for review one pair at a time. That is the right tool below 50 records. It has no field-level survivorship control, so the primary’s values win wherever both records hold one, and it produces no artifact a reviewer can read afterward.

vs scripting the REST API directly. You end up writing pagination, retry, backoff, and the 10,000-result sharding logic yourself, which is a week of work that the CLI already ships. Script directly when you need an object or endpoint the Agent CLI does not cover yet; otherwise the beta CLI plus a policy layer is the shorter path.

Related: mcp-server-hubspot-cs for read-oriented HubSpot access from Claude, and weekly-pipeline-report-skill for the reporting job that stale-deal disposition feeds.

Edit this page on GitHub

Files in this artifact

Download all (.zip)

---
name: hubspot-crm-hygiene-governed
description: Runs bulk CRM hygiene in HubSpot through the HubSpot Agent CLI under a written policy — dedupe with field-level survivorship, property backfill with provenance stamping, and stale-deal disposition — producing a reviewable change ledger and a pre-image snapshot before any irreversible write. Use when a hygiene run has to be repeatable, reviewable, or auditable rather than a one-off cleanup.
---

# Governed CRM hygiene via the HubSpot Agent CLI

This Skill does not replace HubSpot's official Agent CLI skills. It governs them. Install the vendor bundle first:

```
npx skills add hubspot/agent-cli-skills
```

That bundle supplies the mechanics — JSONL pipes, batch reads, pagination, `--dry-run`/confirm patterns, and `hubspot history` recovery. What it does not supply is policy: which duplicate wins field by field, where a backfilled value came from, when a deal is dead versus merely quiet, and what record of the run survives afterward. This Skill is that policy layer, plus the safety rails that `--dry-run` alone cannot provide.

## When to invoke

Invoke when a HubSpot hygiene job has to satisfy at least one of these:

- It runs on a schedule, headless, with no human watching each mutation.
- Someone other than the operator will review what changed and why.
- The changed properties feed reporting, routing, scoring, or comp — so a silent bad write has downstream cost.
- The job touches more than ~200 records, where manual pair-by-pair review stops being realistic.

## When NOT to invoke

- **One-off cleanup by the person who owns the portal.** The vendor's `crm-data-quality` skill handles it with less setup. Policy files are overhead when the operator is also the reviewer and the run happens once.
- **No sandbox and no snapshot budget.** Merges cannot be undone. If you cannot write a pre-image snapshot to disk, stop.
- **The survivorship rule has not been decided.** This Skill applies a rule you supply. It will not invent one. An unfilled `references/1-survivorship-policy.md` is a hard stop, not a default.
- **Fewer than ~50 records.** Below that, the in-app duplicate manager and manual review beat the setup cost.
- **Active enrollment triggers on the target properties have not been audited.** Property writes fire HubSpot workflows. See Watch-out 4.

## Inputs

| Input | Required | Type | Notes |
|---|---|---|---|
| `object_type` | yes | string | `contacts`, `companies`, `deals`, `tickets`, or a custom object type. One per run. |
| `job` | yes | enum | `dedupe`, `backfill`, or `stale-deals`. One per run — never combined. |
| `scope_filter` | yes | string | A CLI filter expression narrowing the working set. An unfiltered portal-wide run is refused. |
| `run_dir` | yes | path | Output directory. Defaults to `./crm-hygiene-<object_type>-<job>-<YYYY-MM-DD>/`. |
| `policy_files` | yes | paths | The filled reference files below. |
| `apply` | no | bool | Defaults to `false`. When false the run stops after the ledger. |
| `max_mutations` | no | int | Per-class ceiling. Defaults to 250. Exceeding it aborts rather than truncates. |

## Reference files

Fill these before the first run. Placeholder content is scaffolding, not defaults.

- `references/1-survivorship-policy.md` — match rules for duplicate detection and the field-level winner table.
- `references/2-backfill-provenance.md` — source precedence, provenance property names, rollback procedure.
- `references/3-stale-deal-disposition.md` — staleness thresholds per stage and the disposition decision table.

## Method

The Skill runs six phases in fixed order. It refuses to skip forward.

**Phase 1 — pin and verify.** Record `hubspot --version` into `<run_dir>/ledger/run-meta.json`. Confirm the authenticated identity with `hubspot whoami`. The CLI is in public beta and HubSpot states that commands, flags, and behavior can change without notice, so the version that produced a ledger is part of the ledger. If the recorded version differs from the previous run's, the Skill prints the delta and asks for confirmation before proceeding.

Discovery runs under `hubspot auth login` OAuth, never under a service key. Reason: OAuth is scoped to the user's own permissions, so a scoping mistake in a read phase fails closed instead of quietly reading everything.

**Phase 2 — scope and snapshot.** Resolve `scope_filter` into a working set and write a pre-image to `<run_dir>/pre-image/<object_type>.jsonl`, one full record per line, with every property the policy touches plus `id`, `createdate`, `hs_lastmodifieddate`.

Why a snapshot when the CLI has `--dry-run` and HubSpot has `hubspot history`: `--dry-run` previews a write you have not made yet, and `history` recovers property values on a record that still exists. Neither helps after a merge. A merge is irreversible — HubSpot documents no unmerge path — and the losing record stops existing. The snapshot is the only artifact that can reconstruct what was there. The Skill refuses to enter Phase 5 if the snapshot file is missing or its line count does not match the working-set count.

**Phase 3 — deterministic candidate generation.** Matching runs as code, not as a model judgment: normalize (lowercase, trim, strip `+tag` from email local parts, strip `www.` and protocol from domains), then apply the match rules from the policy file in priority order. Each candidate group is written to `<run_dir>/candidates.jsonl` with the rule that matched it.

Why deterministic: a model asked to re-rank the same duplicate set twice will not return the same grouping twice, which makes the diff between two runs unreviewable and makes a reviewer's approval meaningless. Model judgment is used in exactly one place — Phase 4's ambiguous band — and its output is advisory, flagged, and never auto-applied.

**Phase 4 — resolve under policy.** For `dedupe`, the Skill computes the surviving value **per field**, not per record. This is the phase that exists because of a specific HubSpot behavior: `hubspot objects merge` keeps the primary record's values where both records have a value. A record-level choice therefore discards good data sitting on the secondary — the newer phone number, the corrected job title, the non-empty lifecycle stage.

So the Skill inverts the order. It writes the winning field values onto the primary with `objects update` **first**, then merges. After the merge the primary already holds every winning value, and the merge only has to fold associations and activity history. Groups where the policy cannot pick a winner go to `<run_dir>/ambiguous.jsonl` for human review and are excluded from apply.

For `backfill`, values resolve by the source precedence in the provenance file, and every write carries the provenance stamp. For `stale-deals`, the disposition table maps stage plus days-since-`hs_lastmodifieddate` to one of `close-lost`, `reassign`, `reopen`, or `leave`.

**Phase 5 — dry-run ledger.** Every planned mutation is issued with `--dry-run` and `--format json`, and the responses are folded into `<run_dir>/ledger/changes.jsonl` — one line per record, carrying `id`, operation, per-field before/after, the policy rule that authorized it, and the matched candidate group. A human-readable digest lands at `<run_dir>/ledger/digest.md`: counts by operation, counts by rule, the 20 largest field-value deltas, and the full ambiguous list.

If any mutation class exceeds `max_mutations`, the run aborts here and writes nothing. It does not truncate to the cap — a truncated hygiene run leaves the portal in a half-applied state that is worse than either endpoint.

**Phase 6 — gated apply.** Only with `apply: true`. Mutations replay from the ledger, so what executes is the reviewed artifact rather than a freshly recomputed plan. Requests are paced under the account's burst ceiling with exponential backoff on `429`. Failures are quarantined to `<run_dir>/failed.jsonl` with the API error attached and are never blind-retried — a merge that failed on the 250-merge cap will fail identically on retry, and a retry loop against a partially applied merge is how a cleanup becomes an incident.

Post-apply, the Skill re-reads every touched record and writes `<run_dir>/ledger/verified.jsonl`, marking any record whose post-state does not match the ledger's intent.

## Output format

`digest.md` looks like this:

```markdown
# CRM hygiene digest — contacts / dedupe — 2026-08-03
CLI version: 1.4.2 · Auth: oauth (user: ops@example.com) · Mode: DRY RUN
Working set: 12,480 · Candidate groups: 604 · Records affected: 1,247

## Operations
| Operation | Count | Authorizing rule |
|---|---|---|
| objects update (survivorship pre-write) | 1,247 | S-02 newest-non-empty |
| objects merge | 604 | M-01 exact-email |
| deferred to ambiguous.jsonl | 38 | — |

## Largest field deltas
| id | field | before | after | rule |
|---|---|---|---|---|
| 701 | jobtitle | (empty) | VP Revenue Operations | S-02 |
| 884 | phone | +1-555-0134 | +1-555-0199 | S-04 newest-verified |

## Blocked
| id | reason |
|---|---|
| 2291 | merge cap: 250 lifetime merges reached |
```

`changes.jsonl`, one line:

```json
{"run_id":"2026-08-03T09:14:02Z","object_type":"contacts","op":"objects update","id":"701","before":{"jobtitle":null},"after":{"jobtitle":"VP Revenue Operations"},"rule":"S-02","group":"g-0117","provenance":"hygiene_run_2026-08-03"}
```

## Watch-outs

1. **A merge cannot be undone, and `--dry-run` does not change that.** The preview shows the intended result; it does not create a restore point. **Guard:** Phase 2's pre-image snapshot is mandatory and Phase 5 hard-fails without it. Keep `run_dir` for at least one renewal cycle — it is the only reconstruction path for a record that no longer exists.

2. **Merges fail at the 250-merge lifetime cap.** HubSpot blocks a merge when the two records have been involved in 250 or more merges combined, and merges also fail when the result would exceed configured association limits. On a portal with years of accumulated cleanup, these failures cluster in the middle of a run. **Guard:** failures quarantine to `failed.jsonl` and stop that group. No blind retry, and the run continues with the remaining groups rather than aborting.

3. **A backfilled value is indistinguishable from a human-entered one unless you stamp it.** Six months later nobody can tell which records were touched, so nobody can roll the backfill back or exclude it from an analysis. **Guard:** every backfill write also sets the two provenance properties defined in `references/2-backfill-provenance.md` (`hygiene_source`, `hygiene_run_id`). Create them before the first run; the rollback procedure in that file keys on `hygiene_run_id`.

4. **Property writes fire workflow enrollment triggers.** A lifecycle-stage backfill across 4,000 contacts can enroll all of them in a nurture sequence and send 4,000 emails to customers. This is the failure mode with the largest blast radius on this page, and it originates outside the CLI entirely. **Guard:** before any `backfill` run, enumerate active workflows whose enrollment triggers reference the target properties, and either pause them or exclude the working set for the duration. The Skill prints the target property list at Phase 4 and requires explicit confirmation that this audit happened.

5. **Admin mode widens the blast radius past your own permissions.** A `HUBSPOT_ACCESS_TOKEN` service key is account-level, and HubSpot requires it for schema operations and most deletes. A key exported into a long-lived shell stays live for every later command in that session. **Guard:** discovery and dry-run phases run under OAuth. When admin mode is genuinely required, export the key inside a subshell scoped to that single command so it does not leak into the rest of the run.

6. **Beta drift breaks a pinned run silently.** HubSpot states flags and behavior can change without notice, and the CLI auto-upgrades by default. A flag that vanishes between two scheduled runs turns a governed run into an ungoverned one. **Guard:** set `HUBSPOT_NO_AUTO_UPGRADE=1` for scheduled runs, pin the version in `run-meta.json`, and treat a version delta as a review trigger rather than a routine upgrade.

7. **The Search API caps at 10,000 results per query.** A working set larger than that silently stops at the cap, or returns a `400` when paging past it, and the hygiene run then reports clean on records it never read. **Guard:** the Skill shards `scope_filter` by `createdate` ranges when the working-set estimate exceeds 9,000 and asserts that the union of shard counts matches the unsharded count estimate.

# Survivorship policy

Last edited: 2026-08-03 · Owner: `REPLACE_WITH_OWNER` · Portal: `REPLACE_WITH_HUB_ID`

This file decides two things: which records are duplicates, and which value wins per field. The Skill hard-stops if the winner table still contains `REPLACE_` placeholders. There is no default rule — an unfilled file means the argument has not been had yet.

## Part A — match rules

Rules run in priority order. The first rule that matches a pair assigns the group. Lower `id` prefix wins ties only for determinism, never for data quality.

| Rule | Object | Match condition | Confidence | Action |
|---|---|---|---|---|
| M-01 | contacts | Normalized `email` exact match | high | auto-group |
| M-02 | contacts | Normalized `phone` exact match AND same `associatedcompanyid` | high | auto-group |
| M-03 | contacts | `firstname` + `lastname` exact AND same `associatedcompanyid` | medium | ambiguous |
| M-04 | companies | Normalized `domain` exact match | high | auto-group |
| M-05 | companies | `name` exact match AND same `country` | medium | ambiguous |
| M-06 | deals | `dealname` exact AND same `associatedcompanyid` AND same pipeline | medium | ambiguous |

Normalization applied before every comparison: lowercase, trim whitespace, strip `+tag` from the email local part, strip protocol and leading `www.` from domains, reduce phone numbers to digits with country code.

`auto-group` proceeds to the winner table. `ambiguous` is written to `ambiguous.jsonl` and never applied without a human decision.

**Tune the confidence column, not the rule list.** Demoting M-02 to `ambiguous` is the correct first move on a portal with shared switchboard numbers. Promoting M-03 to `auto-group` is almost always wrong — common names inside one large account collide.

## Part B — primary record selection

The primary is the record that survives the merge and keeps its `id`. Downstream integrations key on that `id`, so the choice matters beyond data quality.

Selection order — first non-tied criterion wins:

1. Record with the most associated deals (protects revenue history).
2. Record with the earliest `createdate` (protects original-source attribution).
3. Record with the lowest `id`.

`REPLACE_IF_DIFFERENT` — if an external system (billing, product, warehouse) holds a HubSpot record id as a foreign key, that record must be primary regardless of the above. List those systems and their object types here.

## Part C — field-level winner table

This is the table that makes the merge safe. HubSpot's `objects merge` keeps the **primary's** value wherever both records hold one, so any field where the secondary is better must be pre-written onto the primary before the merge runs. The Skill performs that pre-write automatically for every field marked `pre-write: yes`.

| Field | Winner rule | Pre-write | Notes |
|---|---|---|---|
| `email` | primary | no | The merge preserves the secondary's email as an additional email on the primary. |
| `firstname` / `lastname` | S-01 longest-non-empty | yes | Guards against truncated form imports (`Jo` vs `Johanna`). |
| `jobtitle` | S-02 newest-non-empty | yes | Titles change; newest by `hs_lastmodifieddate` wins. |
| `phone` | S-04 newest-verified | yes | Prefer a value whose source is not a self-serve form. |
| `lifecyclestage` | S-03 furthest-forward | yes | Never regress a customer to a lead. Order: subscriber, lead, MQL, SQL, opportunity, customer, evangelist. |
| `hubspot_owner_id` | primary | no | Reassignment is a separate decision from dedupe. Do not fold it in here. |
| `hs_lead_status` | S-03 furthest-forward | yes | Same ordering argument as lifecycle stage. |
| `REPLACE_CUSTOM_FIELD` | `REPLACE_RULE` | `REPLACE` | Add one row per custom property that carries reporting or routing weight. |

Rule definitions:

- **S-01 longest-non-empty** — the longer string wins; ties go to the primary.
- **S-02 newest-non-empty** — the value on the record with the later `hs_lastmodifieddate` wins, ignoring empties.
- **S-03 furthest-forward** — the value further along the declared ordering wins, regardless of recency.
- **S-04 newest-verified** — among values whose source property is in the trusted-source list, the newest wins; if none are trusted, fall back to S-02.

Trusted sources for S-04: `REPLACE_WITH_TRUSTED_SOURCES` (for example: sales-entered, enrichment vendor, verified-by-support).

## Part D — never touch

Fields excluded from every survivorship decision. The Skill refuses to write these even when a rule would select them.

```
hs_object_id
createdate
hs_analytics_source
hs_analytics_first_touch_converting_campaign
REPLACE_WITH_COMPLIANCE_FIELDS
```

Attribution and consent fields belong here. Rewriting first-touch attribution during a cleanup silently rewrites marketing history, and the change is invisible in a dashboard until a quarter-over-quarter comparison stops reconciling.

# Backfill provenance

Last edited: 2026-08-03 · Owner: `REPLACE_WITH_OWNER`

A backfilled value that carries no provenance is a value nobody can audit, roll back, or exclude from an analysis. Six months after the run, a blank-turned-populated `industry` field looks exactly like one a rep typed. This file defines where values come from, what gets stamped alongside them, and how to reverse the run.

## Part A — provenance properties

Create these two custom properties on every object type this Skill backfills, before the first run. The Skill hard-stops if they do not exist.

| Property | Type | Purpose |
|---|---|---|
| `hygiene_source` | single-line text | Which source supplied the value (`enrichment:REPLACE_VENDOR`, `derived:domain`, `inherited:company`, `default:policy`). |
| `hygiene_run_id` | single-line text | The run that wrote it. Format `hygiene_<job>_<YYYY-MM-DD>`. Rollback keys on this. |

Both are set on the same `objects update` call as the backfilled value, never in a second pass. A second pass leaves a window where a crash produces stamped-but-unwritten or written-but-unstamped records, and reconciling that window by hand costs more than the backfill saved.

Exclude both properties from every enrollment trigger, list definition, and report filter. They are metadata about the record, not facts about the customer.

## Part B — source precedence

Per target property, the first source that returns a non-empty value wins. Sources below the line marked `STOP` are never used to overwrite an existing value.

| Target property | 1st source | 2nd source | 3rd source | Overwrite non-empty? |
|---|---|---|---|---|
| `industry` | enrichment vendor | inherited from associated company | — | no |
| `numberofemployees` | enrichment vendor | — | — | yes, when the existing value is older than 365 days |
| `country` | enrichment vendor | derived from phone country code | derived from email TLD | no |
| `lifecyclestage` | derived from deal stage | — | — | no, forward-only per the S-03 ordering |
| `hubspot_owner_id` | territory rule | — | — | no |
| `REPLACE_TARGET` | `REPLACE_SOURCE` | — | — | `REPLACE` |

**Default to `no` in the overwrite column.** A backfill exists to fill blanks. The moment it overwrites populated fields it stops being hygiene and becomes a data migration, which needs a different review and a different approval.

The one row above that overwrites (`numberofemployees`) does so on an explicit staleness test, not on a blanket rule. Copy that shape for any other field you promote.

## Part C — derived-value rules

Derived values are computed, not fetched. Each one needs a stated rule so a reviewer can check the arithmetic.

- **`country` from phone** — map the country calling code to ISO 3166 alpha-2. Ambiguous codes (`+1` covers the US, Canada, and several Caribbean nations) resolve to `unknown`, never to a guess.
- **`country` from email TLD** — country-code TLDs only. Never derive from `.com`, `.io`, `.ai`, or any gTLD.
- **`lifecyclestage` from deal stage** — an associated deal in a closed-won stage implies `customer`. No other deal stage implies a forward move.

Anything you cannot state as a rule this short does not belong in a backfill. It belongs in a reviewed enrichment workflow with a human in the loop.

## Part D — rollback

Rollback is why the stamp exists. To reverse run `hygiene_backfill_2026-08-03`:

1. Read every record where `hygiene_run_id` equals the run id. This is the authoritative affected set — do not reconstruct it from the ledger, which records intent rather than result.
2. For each, look up the pre-image line in `<run_dir>/pre-image/<object_type>.jsonl` by `id`.
3. Write back only the properties the ledger lists for that record. Restoring the whole pre-image record would revert unrelated edits made by humans since the run.
4. Clear `hygiene_source` and `hygiene_run_id`.
5. Re-read the affected set and confirm the property values match the pre-image.

Step 3 is the one people get wrong. A blanket restore looks safer and is not — it silently discards every legitimate edit made in the intervening days.

## Part E — retention

Keep `run_dir` for `REPLACE_WITH_RETENTION_PERIOD` (suggested: 13 months, so a year-over-year comparison can still explain a discontinuity). The pre-image contains customer personal data, so store it where your CRM data-handling policy already applies and delete it on the same schedule as other CRM exports.

# Stale-deal disposition

Last edited: 2026-08-03 · Owner: `REPLACE_WITH_OWNER` · Pipeline: `REPLACE_WITH_PIPELINE_NAME`

Closing stale deals is the highest-friction job in this Skill, because the records belong to reps and the write changes a number leadership watches. This file exists so the rule is argued once with the sales leader who owns the pipeline, written down, and then applied identically every run.

Fill one copy of this file per pipeline. Thresholds that fit a 14-day transactional cycle will gut an enterprise pipeline.

## Part A — what counts as stale

Staleness is measured as days since `hs_lastmodifieddate`, not days since `createdate`. A 400-day-old deal worked last week is healthy; a 30-day-old deal untouched since creation is not.

`hs_lastmodifieddate` moves on any property write, including writes from automation. If a workflow stamps a property on every deal nightly, every deal reads as fresh and this job finds nothing. Confirm that before trusting the first run's output — a stale-deal report that returns zero rows on a pipeline everyone knows is clogged is measuring the automation, not the pipeline.

Where a nightly workflow does touch every deal, switch the measure to the most recent engagement (`notes_last_updated` or last logged activity) and record the substitution here.

## Part B — thresholds per stage

Threshold in days since last modification. Set each with the rep-facing owner, not alone.

| Stage | Stale after | Rationale |
|---|---|---|
| Appointment scheduled | 21 | A meeting either happened or did not inside three weeks. |
| Qualified to buy | 45 | `REPLACE_WITH_YOUR_MEDIAN_STAGE_DURATION` × 2 is the usual starting point. |
| Presentation scheduled | 30 | |
| Decision maker bought-in | 60 | Late-stage deals go quiet for real procurement reasons. Be slow here. |
| Contract sent | 90 | Legal and procurement cycles are long; closing these early destroys real pipeline. |
| `REPLACE_STAGE` | `REPLACE` | |

Set the threshold at roughly twice the stage's median duration, measured from your own closed-won history. Halving that number does not surface more real dead deals — it surfaces more live ones and teaches reps to distrust the job.

## Part C — disposition decision table

Staleness alone never closes a deal. The disposition combines staleness with three other signals.

| Stale | Owner active? | Amount ≥ threshold | Recent engagement | Disposition |
|---|---|---|---|---|
| yes | yes | no | none in stale window | `close-lost` |
| yes | yes | yes | none in stale window | `flag-for-review` |
| yes | no (deactivated) | any | any | `reassign` |
| yes | yes | any | engagement newer than last modification | `leave` |
| yes | yes | any | close date in the past, stage open | `flag-for-review` |
| no | any | any | any | `leave` |

Amount threshold: `REPLACE_WITH_AMOUNT` (suggested: the value above which a deal gets an executive review — commonly the same number that triggers deal-desk involvement).

Two rules carry most of the safety. Large deals never auto-close; they route to a human. And a deal whose owner has been deactivated is a data problem, not a dead deal — reassign it before judging it, or you will close pipeline that nobody has looked at because nobody could.

## Part D — close-lost reason taxonomy

Every auto-closed deal gets a reason, and the reason must distinguish itself from a rep-entered one. A pipeline where hygiene-closed and rep-closed deals share a reason code produces a win/loss analysis nobody can trust.

| Code | Meaning |
|---|---|
| `hygiene-stale-no-activity` | Auto-closed by this job. The only code the job writes. |
| `REPLACE_EXISTING_CODES` | Your existing rep-entered reasons. List them so the job never writes one. |

Set `closed_lost_reason` to `hygiene-stale-no-activity` and stamp `hygiene_run_id` from `references/2-backfill-provenance.md` on every deal the job closes. Exclude that code from win/loss reporting by default — these deals were not lost to a competitor, they were lost to neglect, and mixing the two inflates whatever category they land in.

## Part E — notification

Auto-closing a rep's deal without telling them is how this job gets banned. Before apply, post the per-owner list to the owner and hold for `REPLACE_WITH_HOLD_PERIOD` (suggested: 3 business days). Reps reopen what is actually live, and the reopen rate is the calibration signal for Part B.

A reopen rate above 15% means the thresholds are too aggressive. Raise them before the next run rather than arguing each case.