claude-skill

Run governed CRM hygiene through the HubSpot Agent CLI

Difficulty

avancé

Setup time

60-90 min

For

revops · gtm-engineer

RevOps

Stack

Un Claude Skill qui pilote le HubSpot Agent CLI sur l’hygiène CRM en masse — déduplication, remplissage de propriétés et clôture des deals dormants — sous une politique écrite, en produisant un registre de modifications relisible et un instantané de l’état antérieur avant toute écriture irréversible. Le bundle est publié dans apps/web/public/artifacts/hubspot-agent-cli-crm-cleanup-skill/ et contient SKILL.md ainsi que trois fichiers de référence que vous remplissez avant la première exécution.

Commençons par ce que la plupart des pages passeraient sous silence : HubSpot publie déjà des skills gratuits qui font ici le travail mécanique. npx skills add hubspot/agent-cli-skills installe 15 skills, dont bulk-operations (pipes JSONL, lectures par lot, pagination, motifs dry-run/confirmation, récupération via hubspot history), crm-data-quality (trouver les enregistrements incomplets, normaliser les valeurs, dédupliquer via objects merge) et deal-management (repérer les deals dormants et les clôturer). Installez-les d’abord. Ce Skill ne les remplace pas et ne les réimplémente pas.

Ce que le bundle de l’éditeur ne fournit pas, c’est la politique. Il vous donne les idiomes pour fusionner des enregistrements ; il ne décide pas quel doublon l’emporte champ par champ, d’où vient une valeur ajoutée, quand un deal silencieux est mort plutôt que lent, ni quelle trace de l’exécution subsiste ensuite. Cet écart est toute la raison d’être de ce Skill, et c’est celui qui compte dès qu’un travail d’hygiène tourne en mode headless, planifié, sur un portail que vous n’administrez pas vous-même.

Quand l’utiliser

Utilisez-le lorsqu’un travail d’hygiène HubSpot doit satisfaire au moins une de ces quatre conditions : il tourne de façon planifiée sans personne pour surveiller chaque mutation ; quelqu’un d’autre que l’opérateur relit ce qui a changé ; les propriétés touchées alimentent le routage, le scoring, le reporting ou la rémunération, de sorte qu’une mauvaise écriture a un coût en aval ; ou l’ensemble de travail dépasse environ 200 enregistrements, seuil à partir duquel la relecture paire par paire cesse d’être réaliste.

L’Agent CLI de HubSpot est entré en bêta publique le 2026-06-23, sous forme de binaire distinct du CLI de développement hs. Installez-le avec curl -fsSL https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.sh | sh sous POSIX, ou son équivalent PowerShell sous Windows, puis authentifiez-vous avec hubspot auth login. Les commandes suivent la forme hubspot <noun> <verb>, produisent du JSONL par défaut et acceptent un --dry-run global qui prévisualise les changements sans les appliquer.

Quand NE PAS l’utiliser

Un nettoyage ponctuel sur un portail que vous administrez. Le skill crm-data-quality de l’éditeur le fait avec bien moins de configuration. Les fichiers de politique sont une surcharge quand l’opérateur est aussi le relecteur et que l’exécution n’a lieu qu’une fois.
Vous ne pouvez pas écrire d’instantané sur disque. Les fusions sont définitives. Sans état antérieur, il n’existe aucune voie de reconstruction, et le Skill s’arrête net au lieu de continuer.
La règle de survivance n’est pas tranchée. Le Skill applique une règle que vous fournissez et refuse d’en inventer une. Un references/1-survivorship-policy.md non rempli est un arrêt, pas une valeur par défaut.
Moins de 50 enregistrements. Le gestionnaire de doublons intégré à HubSpot plus une relecture manuelle l’emportent sur le coût de configuration à cette taille.
Vous voulez qu’une exécution fasse les trois travaux. Déduplication, remplissage et traitement des deals dormants exigent chacun une exécution distincte contre un fichier de politique distinct. Les combiner produit un registre qu’aucun relecteur ne peut lire.

Configuration

Prévoyez 60-90 minutes, consacrées surtout au remplissage des fichiers de politique plutôt qu’à des installations. La discussion sur la survivance — quel enregistrement l’emporte et quels champs survivent au perdant — prend plus de temps et a lieu avant la configuration.

Installez le CLI et les skills de l’éditeur. Lancez le script d’installation, puis hubspot auth login, puis hubspot whoami pour confirmer le portail. Ajoutez npx skills add hubspot/agent-cli-skills. Les utilisateurs de Claude Cowork sur des comptes Team ou Enterprise ont besoin qu’un administrateur autorise d’abord api.hubapi.com.
Installez ce Skill. Copiez SKILL.md et le dossier references/ dans .claude/skills/hubspot-crm-hygiene/. Le name et la description du frontmatter sont ce qui le déclenche sur un prompt pertinent.
Créez les deux propriétés de provenance. hygiene_source et hygiene_run_id, texte sur une ligne, sur chaque type d’objet que vous comptez remplir. Les définitions figurent dans references/2-backfill-provenance.md. Le Skill s’arrête si elles n’existent pas.
Remplissez references/1-survivorship-policy.md. Règles de correspondance en partie A, sélection de l’enregistrement principal en partie B, tableau des gagnants champ par champ en partie C et liste intouchable en partie D. Les champs d’attribution et de consentement relèvent de la partie D : réécrire l’attribution du premier contact pendant un nettoyage réécrit l’historique marketing de façon invisible.
Remplissez references/3-stale-deal-disposition.md avec le responsable du pipeline présent. Fixez chaque seuil d’étape à environ deux fois la durée médiane de cette étape dans votre propre historique closed-won.
Auditez les déclencheurs d’inscription des workflows. Listez les workflows actifs dont les déclencheurs référencent une propriété cible. Cette étape n’est pas facultative ; voyez le quatrième mode de défaillance.
Faites un dry-run sur un périmètre de 200 enregistrements. Lisez ledger/digest.md de bout en bout et vérifiez que la liste des cas ambigus ressemble à de vrais arbitrages plutôt qu’à une règle de correspondance mal calibrée.

Ce que le skill fait réellement

Six phases, ordre fixe, sans saut en avant.

La phase 1 fige l’environnement. Elle consigne hubspot --version et l’identité authentifiée dans ledger/run-meta.json. HubSpot indique que les commandes, flags et comportements de la bêta peuvent changer sans préavis : la version qui a produit un registre fait donc partie du registre. La découverte tourne sous OAuth plutôt que sous une service key, parce qu’OAuth est borné aux permissions de l’opérateur et qu’une erreur de périmètre échoue alors en position fermée.

La phase 2 prend l’instantané. Chaque enregistrement du périmètre est écrit dans pre-image/<object_type>.jsonl avant toute autre opération. La raison est précise : --dry-run prévisualise une écriture que vous n’avez pas encore faite, et hubspot history restaure des valeurs de propriétés sur un enregistrement qui existe encore. Aucun des deux n’aide après une fusion, car HubSpot ne documente aucune voie de retour et l’enregistrement perdant cesse d’exister. La phase 5 refuse de démarrer si l’instantané manque ou si son nombre de lignes ne correspond pas à l’ensemble de travail.

La phase 3 génère les candidats de façon déterministe. Normalisation et règles de correspondance s’exécutent comme du code, sans jugement du modèle. Un modèle à qui l’on demande de regrouper deux fois le même ensemble de doublons ne rendra pas deux fois le même regroupement, ce qui rend le diff entre deux exécutions impossible à relire et vide de sens l’approbation d’un relecteur. Le jugement du modèle intervient à un seul endroit, la bande ambiguë, où sa sortie est consultative et jamais appliquée automatiquement.

La phase 4 tranche selon la politique, champ par champ et non enregistrement par enregistrement. Cette phase existe à cause d’un comportement précis de HubSpot : objects merge conserve la valeur de l’enregistrement principal partout où les deux enregistrements en portent une. Choisir un principal revient donc à jeter de bonnes données du secondaire — le téléphone plus récent, l’intitulé de poste corrigé, l’étape de cycle de vie renseignée. Le Skill inverse donc l’ordre. Il pré-écrit les valeurs gagnantes sur le principal via objects update, puis fusionne, de sorte que la fusion ne fait plus que replier les associations et l’historique d’activité. Les groupes que la politique ne peut trancher partent dans ambiguous.jsonl et restent exclus de l’application.

La phase 5 construit le registre. Chaque mutation prévue est émise avec --dry-run --format json puis repliée dans ledger/changes.jsonl — une ligne par enregistrement, avec les valeurs avant/après et la règle qui a autorisé la modification — plus un ledger/digest.md lisible par un humain. Si une classe de mutations dépasse max_mutations (250 par défaut), l’exécution s’interrompt ici et n’écrit rien. Elle ne tronque pas au plafond, car une hygiène appliquée à moitié laisse le portail dans un état pire que l’un ou l’autre des points de départ.

La phase 6 applique, sous condition. Les mutations sont rejouées depuis le registre et non depuis un plan recalculé : ce qui s’exécute est donc l’artefact qui a été relu. Les échecs sont mis en quarantaine dans failed.jsonl et ne sont jamais retentés à l’aveugle. Ensuite, chaque enregistrement touché est relu dans ledger/verified.jsonl.

Coût et débit réels

La contrainte qui mord, ce sont les limites d’API de HubSpot, pas les tokens.

La découverte s’appuie sur la CRM Search API, plafonnée à 5 requêtes par seconde et par compte, qui renvoie au plus 200 objets par page et bute sur un plafond dur de 10 000 résultats par requête — paginer au-delà renvoie un 400. Un ensemble de travail de 12 000 contacts doit donc être découpé par createdate en au moins deux requêtes. À 200 enregistrements par page et 5 requêtes par seconde, la découverte lit environ 1 000 enregistrements par seconde : un périmètre de 50 000 enregistrements prend donc à peu près une minute.

Les écritures sont bornées par le plafond de rafale : 190 requêtes par tranche de 10 secondes pour les apps privées Professional et Enterprise, 100 pour Free et Starter, 250 avec l’option API Limit Increase. Les plafonds journaliers sont de 625 000 appels en Professional et 1 000 000 en Enterprise. Une déduplication de 600 groupes coûte environ 1 850 appels en écriture — une pré-écriture de survivance par enregistrement concerné, plus une fusion par groupe — soit près de 100 secondes de temps d’API pur en Professional et environ 0,3 % du quota journalier.

Le coût en tokens est faible par construction, parce que la correspondance est déterministe. Seule la bande ambiguë atteint le modèle, et à 30-60 groupes pour 10 000 enregistrements avec environ 800 tokens d’entrée par groupe, une exécution complète coûte nettement moins d’un dollar en tokens Claude. Le vrai coût, c’est la séance de politique de 60-90 minutes, un coût unique amorti sur toutes les exécutions suivantes.

Métrique de succès

Suivez le taux de création de doublons, pas le nombre de doublons supprimés. Les doublons supprimés mesurent à quel point le portail était sale ; le taux de création mesure si la voie d’entrée qui les produit a été corrigée. Lancez le travail de déduplication chaque mois et tracez les nouveaux groupes de doublons pour 1 000 enregistrements créés. Une courbe plate ou montante signifie que les réglages de déduplication des formulaires, les imports de listes ou une intégration continuent de produire des collisions, et aucun volume de nettoyage ne rattrapera cela.

La métrique secondaire est la taille de la bande ambiguë. Elle doit se réduire à mesure que les règles de correspondance sont affinées. Une bande qui reste au-dessus de 10 % des groupes candidats signifie qu’une règle de la partie A est mal calibrée.

Pour les deals dormants, le signal de calibration est le taux de réouverture pendant le délai de notification. Au-dessus de 15 %, les seuils sont trop agressifs : relevez-les au lieu de discuter deal par deal.

Modes de défaillance

Une fusion est irréversible, et --dry-run n’y change rien. L’aperçu montre le résultat visé sans créer de point de restauration. HubSpot n’offre aucune annulation de fusion. Garde-fou : l’état antérieur de la phase 2 est obligatoire et la phase 5 échoue sans lui. Conservez run_dir au moins un cycle de renouvellement — c’est la seule voie de retour pour un enregistrement qui n’existe plus.
Les fusions échouent au plafond de 250 fusions cumulées. HubSpot bloque une fusion dès que deux enregistrements ont participé à 250 fusions ou plus au total, et une fusion échoue aussi lorsque le résultat dépasserait les limites d’associations configurées. Sur un portail avec des années d’historique de nettoyage, ces échecs se concentrent en milieu d’exécution. Garde-fou : les échecs sont mis en quarantaine dans failed.jsonl avec l’erreur d’API jointe et n’arrêtent que ce groupe. Aucun retry à l’aveugle — le même appel échoue à l’identique, et retenter sur une fusion partiellement appliquée est la façon dont un nettoyage devient un incident.
Les écritures de propriétés déclenchent des inscriptions à des workflows. Un remplissage d’étape de cycle de vie sur 4 000 contacts peut inscrire les 4 000 dans une séquence de nurture et envoyer 4 000 emails à des clients existants. C’est le rayon d’impact le plus large de cette page, et il naît entièrement hors du CLI. Garde-fou : énumérez les workflows actifs dont les déclencheurs d’inscription référencent les propriétés cibles, puis mettez-les en pause ou excluez l’ensemble de travail le temps de l’exécution. Le Skill affiche la liste des propriétés cibles en phase 4 et exige une confirmation explicite que cet audit a bien eu lieu.
Une valeur ajoutée par remplissage est indiscernable d’une valeur saisie par un humain. Des mois plus tard, personne ne peut dire quels enregistrements le travail a touchés, donc personne ne peut l’annuler ni l’exclure d’une analyse. Garde-fou : chaque écriture de remplissage pose hygiene_source et hygiene_run_id dans le même appel objects update — pas dans une seconde passe, qui laisse une fenêtre de plantage avec des enregistrements estampillés mais non écrits. La procédure d’annulation de references/2-backfill-provenance.md s’appuie sur l’identifiant d’exécution et ne restaure que les propriétés nommées par le registre, de sorte que les modifications humaines faites depuis survivent.
Le mode admin porte au-delà de vos propres permissions. HubSpot exige une service key HUBSPOT_ACCESS_TOKEN pour les opérations de schéma et la plupart des suppressions, et cette clé est au niveau du compte. Exportée dans un shell à longue durée de vie, elle reste active pour toutes les commandes suivantes. Garde-fou : exécutez la découverte et le dry-run sous OAuth, et exportez la service key dans un sous-shell limité à la seule commande qui en a besoin.
La dérive de la bêta casse silencieusement une exécution figée. Le CLI se met à jour tout seul par défaut et HubSpot prévient que les flags peuvent changer sans préavis : un flag qui disparaît entre deux exécutions planifiées transforme une exécution encadrée en exécution sans cadre. Garde-fou : posez HUBSPOT_NO_AUTO_UPGRADE=1 pour les exécutions planifiées, figez la version dans run-meta.json et traitez tout écart de version comme un déclencheur de relecture.

vs les alternatives

vs les skills officiels HubSpot seuls. Ils sont gratuits, maintenus par l’éditeur et suivent le CLI au fil de ses changements — de vrais avantages que ce bundle n’a pas. Utilisez-les seuls quand le responsable du CRM lance un nettoyage unique et en relit les résultats directement. Ajoutez cette couche quand l’exécution se répète, quand le relecteur n’est pas l’opérateur, ou quand quelqu’un demandera dans six mois quel travail a écrit une valeur. Le partage honnête : l’éditeur fournit les verbes, ceci fournit la politique et le justificatif.

vs Insycle et les SaaS de déduplication similaires. L’outillage dédié a ici un avantage réel : un responsable ops non technique peut piloter des fusions en masse par gabarits depuis une interface, et Insycle documente une voie d’annulation de fusion que HubSpot lui-même n’offre pas. Achetez cela quand la personne qui fait l’hygiène n’est pas à l’aise dans un terminal et que le budget existe. Ce Skill l’emporte quand l’hygiène tourne en headless, planifiée, à l’intérieur d’un agent, et quand la politique doit vivre dans le contrôle de version aux côtés du reste de votre configuration ops, là où un diff montre qui a changé la règle de survivance.

vs la gestion des doublons intégrée à HubSpot. Elle est gratuite, ne demande aucune configuration et présente les doublons suggérés pour relecture une paire à la fois. C’est le bon outil en dessous de 50 enregistrements. Elle n’offre aucun contrôle de survivance champ par champ, donc les valeurs du principal l’emportent partout où les deux enregistrements en portent une, et elle ne produit aucun artefact qu’un relecteur puisse lire ensuite.

vs scripter l’API REST directement. Vous finissez par écrire vous-même la pagination, les retries, le backoff et la logique de découpage des 10 000 résultats, soit une semaine de travail que le CLI embarque déjà. Scriptez directement quand vous avez besoin d’un objet ou d’un endpoint que l’Agent CLI ne couvre pas encore ; sinon, le CLI en bêta plus une couche de politique est le chemin le plus court.

À rapprocher de : mcp-server-hubspot-cs pour un accès HubSpot en lecture depuis Claude, et weekly-pipeline-report-skill pour le travail de reporting qu’alimente le traitement des deals dormants.

Modifier cette page sur 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.