tomgranot/hubspot-admin-skills/hubspot-implementation-plan

HubSpot Implementation Plan Generator

Generate a phased, prioritized cleanup and optimization plan from a HubSpot audit report. This skill reads audit findings, sequences them into phases with dependencies, and outputs a detailed implementation roadmap with automation feasibility for each task.

Prerequisites

• A completed audit report in reports/, generated by /hubspot-audit (full), /hubspot-marketing-audit, or /hubspot-sales-audit
• If no audit report exists, ask which side of the portal the user owns and point them at the matching audit

Steps

1. Load the Audit Report

Find the most recent audit report. The audit engine writes one of three names depending on scope:

Each has a .json twin with the same data in structured form: dimensions (grade, rows with count, percentage, and fix skill) and prescription (the ordered skill list). Prefer the JSON for counts and the markdown for context. Extract:

• Letter grades per dimension, and each dimension's lens (shared, marketing, sales)
• Exact counts for each metric
• The Prescription table

If multiple reports exist, use the most recent by date in the filename. If a marketing report and a sales report share a date, plan from both: their shared dimensions are identical, so merge them rather than double-counting.

Plan only what the report covers. A marketing-scoped report yields a plan without the Sales Pipeline phase; a sales-scoped report yields a plan without the deliverability and suppression tasks. Do not pad a scoped plan with tasks the audit did not measure.

2. Generate the Phased Plan

Analyze the audit findings and organize cleanup tasks into five phases. Each phase builds on the previous one. Only include tasks that are relevant based on the audit findings — if a dimension scored A, skip or deprioritize its tasks.

Phase 1: Immediate Hygiene (Week 1-2)

These tasks have direct billing or deliverability impact. Do them first.

Key constraint: hs_marketable_status is read-only via API. All suppression tasks use a hybrid approach:

1. Script sets a custom flag property (e.g., suppress_reason) via API
2. A HubSpot workflow triggers on that flag and sets the contact as non-marketing

This workflow must be built manually in the HubSpot UI before running suppression scripts.

Phase 2: Data Enrichment (Week 3-4)

Fill data gaps to enable segmentation and scoring.

Key constraint: Lifecycle stage is forward-only in HubSpot. To set a contact to an earlier stage, you must first clear the property (set to empty string), then set the desired value. The script must handle this two-step process.

Phase 3: Segmentation & Scoring (Week 4-6)

Build the targeting infrastructure.

Key constraint: Build lead scoring rules in the UI. A beta Lead Scoring API now exists (/marketing/lead-scoring/2027-03-beta/scores) and is useful for snapshotting or cloning a finished score, but it is subject to change and does not document decay. Each score generates CRM properties that ARE readable and filterable via API. Build the scoring model manually based on the ICP tier data from the previous step; verify score distributions via the Search API.

Phase 4: Automation (Week 6-8)

Set up ongoing automated hygiene.

Key update: The v4 Automation API (documented by HubSpot as beta, and subject to change) supports creating, updating, and batch-reading workflows for contacts, companies, deals, and tickets, with all action types (the v3 workflows API is now legacy). The workflow skills are API-first: each ships before/execute/after scripts that create the workflows via POST /automation/v4/flows — always disabled, so a human reviews them in the UI before enabling. Two options per workflow:

1. v4 Automation API (primary) -- Run each skill's scripts, then complete the short UI review. Notes: flows touching sensitive-data properties require the corresponding sensitive-data scopes; a few action types (copy-from-associated-object, internal notifications) have undocumented API field shapes and are added in the UI during review.

1. Manual UI Build (fallback) -- Follow the step-by-step instructions in each skill. Required on plan tiers where the Automation API returns 403. (HubSpot Breeze AI can also scaffold workflows from prompts, but it creates event-based OR triggers instead of filter-based AND triggers and cannot configure re-enrollment or "is unknown" conditions — verify everything it builds. The Claude Chrome extension can drive the workflow builder UI directly.)

Each workflow skill (/new-contact-hygiene-workflow, /engagement-suppression-workflow, /lifecycle-progression-workflow, /bounce-monitoring-workflow) documents both options. The ICP tier classification workflows in /create-icp-tiers are still built in the UI due to their multi-group demotion filter logic. After building, run /workflows-as-code to export everything to versioned JSON.

Sales Pipeline Track (runs alongside Phases 1-2)

Include this track when the report has sales dimensions. It touches deals rather than contacts, so it does not block or depend on the marketing phases, with one exception: reassigning deactivated owners in Phase 1 covers deals and contacts in the same pass.

Key constraint: deal cleanup needs the people who own the deals. Scripts can find every stale or incomplete deal, but only the rep knows whether it is dead. Plan a review session per team rather than a bulk close, and coordinate with the Salesforce admin first if deals sync from Salesforce.

After cleanup, lock in prevention through portal settings: required properties per deal stage, pipeline rules, and a stale-deal task workflow.

Phase 5: Ongoing Maintenance (Ongoing)

Recurring tasks to keep the CRM clean.

3. Build the Dependency Graph

Map dependencies between tasks. A task cannot start until its dependencies are complete: