hubspot-deal-pipeline-automation

What it does

Automates and audits HubSpot deal pipeline operations without destroying real pipeline. It guards against six failure modes in pipelines, audits stale deals, reconciles multiple forecast fields, detects custom property drift, provides cache-busting for quota dashboards, and detects duplicates across pipelines. Trigger phrases include hubspot deal pipeline, hubspot stage automation, hubspot stale deals, hubspot forecast reconciliation, hubspot quota dashboard, hubspot duplicate deals, revops pipeline audit.

How it works

Describes explicit, concrete steps and code snippets to implement safeguards:

• Stage transition guard: creates a sentinel property hs_pipeline_loop_guard and uses it to prevent rapid re-entrant stage changes. Wrap stage-change calls with a function that reads, checks, writes the guard, then performs the transition. Includes a curl-based setup to create the property and a TypeScript wrapper for safeStageTransition, plus a curl-based history check to detect oscillation.
• Stale-deal safe-close audit: defines a safe-close criterion (deal > 90 days old AND no inbound email in last 30 days AND no open tasks) and references Python scripts (stale_deal_audit.py and batch_close_stale.py) located in an implementation guide for usage and CSV output review.
• Forecast amount reconciliation: fetches four amount-like fields (amount, hs_projected_amount, hs_deal_stage_probability, arr_value) and compares to determine staleness. If discrepancy exceeds 5%, forces a patch to the dealstage to trigger a recomputation. Mentions a Python forecast_reconcile.py for bulk recalculations.
• Custom property drift detection: provides a bash script (check-deal-properties.sh) that lists portal properties and verifies that properties_in_use.txt exists in portal schema, failing deployment if missing.
• Quota dashboard cache-busting: shows a TypeScript liveQuotaSnapshot function that queries CRM API directly to compute closedWon and openPipeline for a given pipeline/owner, with asOf timestamp. Advises serving via internal ops dashboard instead of HubSpot report iframe and notes that CRM reflects changes quickly.
• Multi-pipeline duplicate detection: explains dedup logic and references implementation-guide.md sections for findDuplicateDeals and searchAllOpenDeals, including a curl example to link deals via a cross-reference association when duplicates are found.

The skill presents concrete API calls, code blocks, and script usage to implement each protection or audit path.

When to use it

Use when writing or debugging workflow automations that move deals between stages, auditing pipelines for stale or duplicated opportunities, reconciling forecast numbers across reports, or hardening RevOps dashboards against property deletions and reporting-cache lag. Trigger phrases listed in the overview indicate activation conditions.

What it can touch

Uses declared tools Read, Write, Bash(curl:), Bash(jq:), Bash(python3:*). Requires HubSpot API access tokens and environment with curl, jq, and node/python runtimes as described in prerequisites. Also references hubspot-managed endpoints for deals, properties, changelog, searches, and associations.

Caveats

Describes operational safeguards and required access scopes (crm.objects.deals.read, crm.objects.deals.write, crm.schemas.deals.read, crm.schemas.deals.write, crm.associations.read, crm.associations.write, automation), token handling via HubSpot private app token or OAuth, and execution environments (Node.js 18+ or Python 3.10+). No promised outcomes beyond the described safety mechanisms; limits and reliance on portal configuration are noted in code and prerequisites. License: MIT.