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)
• If no audit report exists, instruct the user to run /hubspot-audit first

Steps#

1. Load the Audit Report#

Find the most recent file matching reports/hubspot-audit-*.md. Read it and extract:

• Letter grades per dimension
• Exact counts for each metric
• The priority recommendations section

If multiple reports exist, use the most recent by date in the filename.

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.

TaskTrigger (from audit)SkillAutomationEst. TimeDelete contacts with no email addressData Completeness: missing email count > 0/delete-no-email-contactsFully scriptable1 hrSuppress hard bounced contactsDeliverability: hard bounce count > 0/suppress-hard-bouncedHybrid (API + workflow)1-2 hrsSuppress global unsubscribesDeliverability: global unsub count > 0/suppress-global-unsubscribesHybrid (API + workflow)1-2 hrsSuppress ghost contacts (never engaged)Engagement: never-engaged count > threshold/suppress-ghost-contactsHybrid (API + workflow)2-3 hrsMerge duplicate companiesDuplicates: duplicate domain count > 0/merge-duplicate-companiesFully scriptable2-4 hrsReassign deactivated owner contactsOwner Health: deactivated owners with records > 0/reassign-deactivated-ownersFully scriptable1-2 hrs

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.

TaskTrigger (from audit)SkillAutomationEst. TimeEnrich company name from associationCompleteness: missing company name/enrich-company-nameFully scriptable1-2 hrsEnrich contact industry from companyCompleteness: missing industry/enrich-industryFully scriptable1-2 hrsStandardize country/state valuesCompleteness: inconsistent geo data/standardize-geo-valuesFully scriptable2-3 hrsBackfill country/state from IP or companyCompleteness: missing geo data/backfill-geo-dataFully scriptable2-3 hrsFix lifecycle stagesCompleteness: missing or incorrect lifecycle stages/fix-lifecycle-stagesFully scriptable2-3 hrsAssign unowned contactsOwner Health: unowned contacts > 0/assign-unowned-contactsFully scriptable1-2 hrs

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.

TaskTrigger (from audit)SkillAutomationEst. TimeCreate ICP tier property and workflowsAlways (after enrichment)/create-icp-tiersHybrid (API + workflow)3-4 hrsBuild lead scoring modelAlways (after enrichment)/build-lead-scoringManual UI only4-6 hrsBuild smart lists for segmentsAlways (after scoring)/build-smart-listsFully scriptable (Lists API)2-3 hrsCreate segment lists for campaignsAlways (after smart lists)/create-segment-listsFully scriptable1-2 hrs

Key constraint: HubSpot's lead scoring tool is UI-only. There is no API for configuring scoring rules. Build the scoring model manually based on the ICP tier data from the previous step.

Phase 4: Automation (Week 6-8)

Set up ongoing automated hygiene.

TaskTrigger (from audit)SkillAutomationEst. TimeNew contact hygiene workflowAlways/new-contact-hygiene-workflowManual UI only2-3 hrsEngagement-based suppression workflowEngagement grade D or F/engagement-suppression-workflowManual UI only2-3 hrsLifecycle stage progression workflowAlways/lifecycle-progression-workflowManual UI only2-3 hrsBounce monitoring workflowDeliverability grade C or worse/bounce-monitoring-workflowManual UI only1-2 hrs

Key constraint: The HubSpot Workflows API (v4) is beta and unstable. Do not attempt to create workflows via API. However, you have three options for building each workflow:

1. Manual UI Build -- Follow the step-by-step instructions in each skill. Most reliable, full control over triggers and actions.

2. HubSpot Breeze AI -- Use Breeze (Automation > Workflows > Create workflow > "Describe what you want") to generate a workflow skeleton from a natural language prompt. Each workflow skill includes a ready-to-paste Breeze prompt. Critical caveat: Breeze creates event-based triggers (OR logic) instead of filter-based triggers (AND logic). You MUST manually verify and fix trigger conditions after Breeze generates the workflow. Breeze also cannot create "is unknown" branch conditions, copy properties from associated objects, or configure re-enrollment rules.

3. Claude Anthropic Chrome Extension -- Use the Claude Chrome extension to interact with the HubSpot workflow builder UI directly. Claude can see the UI and click through each step, which is often more accurate than Breeze for complex workflows with nested branches or multi-condition AND triggers.

Each workflow skill ( /new-contact-hygiene-workflow, /engagement-suppression-workflow, /lifecycle-progression-workflow, /bounce-monitoring-workflow) documents all three options with specific guidance and Breeze prompts tailored to that workflow. The ICP tier classification workflows in /create-icp-tiers also include these three options.

Note on Fast Mode: If you're using Claude Code's Fast Mode to speed up workflow creation, be aware of the billing model: Haiku usage is included in your subscription, but Opus in Fast Mode consumes extra credits. For workflow building tasks (which are UI-heavy and may require many interactions), consider whether the speed tradeoff is worth the credit cost.

Phase 5: Ongoing Maintenance (Ongoing)

Recurring tasks to keep the CRM clean.

TaskFrequencySkillAutomationEst. TimeWeekly cleanup routineWeekly/weekly-cleanup-routineChecklist (manual)1 hr/weekClean up unused listsMonthly/cleanup-listsPartially scriptable1-2 hrsClean up unused formsMonthly/cleanup-formsPartially scriptable1-2 hrsClean up stale workflowsMonthly/cleanup-workflowsPartially scriptable1-2 hrsClean up dashboardsQuarterly/cleanup-dashboardsManual UI only1-2 hrsClean up stale dealsQuarterly/cleanup-dealsPartially scriptable2-3 hrsClean up unused propertiesQuarterly/cleanup-propertiesPartially scriptable2-3 hrsReview lead ownersQuarterly/cleanup-lead-ownersPartially scriptable1-2 hrsReview bounced contactsMonthly/review-bounced-contactsPartially scriptable1 hrQuarterly full database auditQuarterly/hubspot-auditFully scriptable1 hr

3. Build the Dependency Graph#

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

text

Phase 1 (all tasks independent of each other, can run in parallel)
  |
  v
Phase 2 (depends on Phase 1 completion)
  - enrich-company-name → enrich-industry (industry comes from company)
  - standardize-geo → backfill-geo (standardize first, then fill gaps)
  - fix-lifecycle-stages (independent)
  - assign-unowned-contacts (independent, but after deactivated owner reassignment)
  |
  v
Phase 3 (depends on Phase 2 completion)
  - create-icp-tiers → build-lead-scoring → build-smart-lists → create-segment-lists
  |
  v
Phase 4 (depends on Phase 3 for full effectiveness, but can start after Phase 2)
  - All workflow tasks are independent of each other
  |
  v
Phase 5 (starts after Phase 4, runs indefinitely)

4. Compute Effort Summary#

Sum up estimated hours and present:

CategoryHoursFully scriptable tasksX hrsHybrid tasks (API + manual workflow)X hrsManual UI tasksX hrsTotal estimated effort****X hrs

5. Key Technical Constraints Summary#

Include this section in every plan:

1. hs_marketable_status is read-only via API — This is the single biggest blocker. Any task that needs to suppress or unsuppress a contact as a marketing contact cannot do so directly via API. Workaround: set a custom flag property via API, then trigger a HubSpot workflow on that flag to change marketing status.

2. HubSpot Workflows API v4 is beta/unstable — Do not attempt to create workflows via API. Build all workflows manually in the HubSpot UI using the specifications from each skill.

3. Lifecycle stage is forward-only — HubSpot prevents setting a contact to an earlier lifecycle stage. To fix this, clear the property first (set to empty string via API), then set the desired stage in a second API call.

4. Search API caps at 10,000 results — Any query that might return more than 10K results must be segmented (e.g., by date range or property value) and summed. This affects most counting queries on large portals.

5. Rate limit: 100 requests per 10 seconds — All scripts must implement rate limiting. Use exponential backoff on HTTP 429 responses.

Output Format#

Save the plan to reports/implementation-plan-{YYYY-MM-DD}.md with this structure:

markdown

# HubSpot CRM Implementation Plan

**Generated:** YYYY-MM-DD
**Based on audit:** hubspot-audit-YYYY-MM-DD.md

## Executive Summary

Based on the audit findings, this portal requires attention across X dimensions.
The most critical issues are:
1. [Top finding from audit]
2. [Second finding]
3. [Third finding]

**Total estimated effort:** XX-XX hours over 6-8 weeks

## Phase 1: Immediate Hygiene (Week 1-2)

**Goal:** Reduce billing costs and protect sender reputation.

### 1.1 Delete Contacts With No Email Address
- **Why:** Contacts without email cannot receive marketing — they are dead weight
  that inflates your contact tier billing.
- **Count from audit:** X,XXX contacts
- **Automation:** Fully scriptable
- **Skill:** `/delete-no-email-contacts`
- **Dependencies:** None
- **Estimated time:** 1 hour
- **Status:** [ ] Not started

### 1.2 Suppress Hard Bounced Contacts
- **Why:** Hard bounces damage sender reputation and deliverability scores.
  These contacts will never receive email again.
- **Count from audit:** X,XXX contacts
- **Automation:** Hybrid — API sets flag, workflow changes marketing status
- **Skill:** `/suppress-hard-bounced`
- **Dependencies:** Suppression workflow must be built in UI first
- **Estimated time:** 1-2 hours
- **Status:** [ ] Not started

### 1.3 Suppress Global Unsubscribes
- **Why:** Globally unsubscribed contacts count toward billing but cannot
  be emailed. Set as non-marketing to reduce costs.
- **Count from audit:** X,XXX contacts
- **Automation:** Hybrid — API sets flag, workflow changes marketing status
- **Skill:** `/suppress-global-unsubscribes`
- **Dependencies:** Suppression workflow must be built in UI first
- **Estimated time:** 1-2 hours
- **Status:** [ ] Not started

...continue for all tasks in all phases...

---

## Dependency Map

```text
[Phase 1] ──→ [Phase 2] ──→ [Phase 3] ──→ [Phase 4] ──→ [Phase 5]
                  │                │
                  ├─ company name  ├─ ICP tiers
                  │   └─→ industry │   └─→ lead scoring
                  ├─ geo std       │       └─→ smart lists
                  │   └─→ geo fill │
                  ├─ lifecycle     │
                  └─ assign owners │

---

Technical Constraints#

1. hs_marketable_status is read-only via API ...
2. Workflows API v4 is beta ...
3. Lifecycle stage is forward-only ...
4. Search API caps at 10K ...
5. Rate limit: 100 req / 10 sec ...

---

Effort Summary#

CategoryTasksHoursFully scriptableXXX hrsHybrid (API + workflow)XXX hrsManual UI onlyXXX hrsOngoing maintenanceXXX hrs/monthTotal initial setupXXX hrs

---

Tracking Checklist#

Phase 1: Immediate Hygiene#

• Delete no-email contacts (X,XXX)
• Suppress hard bounced (X,XXX)
• Suppress global unsubscribes (X,XXX)
• Suppress ghost contacts (X,XXX)
• Merge duplicate companies (X,XXX)
• Reassign deactivated owner contacts (X,XXX)

Phase 2: Data Enrichment#

• Enrich company name from association
• Enrich industry from company
• Standardize country/state values
• Backfill country/state data
• Fix lifecycle stages
• Assign unowned contacts

Phase 3: Segmentation & Scoring#

• Create ICP tier property + workflows
• Build lead scoring model
• Build smart lists
• Create segment lists

Phase 4: Automation#

• New contact hygiene workflow
• Engagement suppression workflow
• Lifecycle progression workflow
• Bounce monitoring workflow

Phase 5: Ongoing Maintenance#

• Weekly cleanup routine established
• Monthly list/form/workflow cleanup scheduled
• Quarterly audit scheduled

text

### 6. Handle Gaps — Missing Skills

After mapping all audit findings to skills, check if any findings have **no matching skill**. This is expected — every HubSpot portal is different and some issues are unique.

For each unmapped finding:

1. **Flag it in the plan**: Add a section called "Custom Skills Needed" listing each gap.

2. **Offer to create the skill**:

The audit found [X] issues that aren't covered by existing skills:

1. [Issue description] — suggested skill name: /[name]
2. [Issue description] — suggested skill name: /[name]

I can create these skills for you right now. Want me to proceed?

text

3. **Ask about upstream contribution**:

These new skills could help other HubSpot admins facing the same issues. Would you like to contribute them back to the community?

If yes, I'll:

• Create each skill following the standard SKILL.md format
• Push them to your fork of hubspot-admin-skills
• Open a pull request to the upstream repo

This is completely optional — you can also keep them local.

text

4. If the user agrees, for each new skill:
- Create `skills/<name>/SKILL.md` with proper frontmatter and the 4-stage pattern
- Add it to the plan as a regular task
- After all skills are created, commit and push to the user's fork
- Open a PR to `tomgranot/hubspot-admin-skills` with a description of what each skill does

### 7. Contribution Quick-Start

If the user wants to help improve the skill set (whether they found gaps or not), provide these instructions:

```markdown
## Want to contribute?

1. **Fork**: `gh repo fork tomgranot/hubspot-admin-skills --clone`
2. **Branch**: `git checkout -b skill/your-skill-name`
3. **Create**: Add `skills/<your-skill>/SKILL.md` following the standard format:
- YAML frontmatter (name, description, license, metadata)
- 4-stage pattern: Plan → Before State → Execute → After State
- API code examples where applicable
- Safety mechanisms and rollback instructions
4. **Test**: Run the skill against a HubSpot sandbox portal
5. **PR**: `gh pr create --repo tomgranot/hubspot-admin-skills`

Your contribution helps every HubSpot admin who uses these skills.

After Running#

• Print the file path of the saved plan
• Highlight the Phase 1 tasks as immediate priorities
• Remind the user to build the suppression workflow in HubSpot UI before running hybrid tasks
• Suggest starting with /delete-no-email-contacts as the first concrete action
• Flag any findings that need custom skills (Step 6) and offer to create them
• Provide the contribution quick-start if the user shows interest in contributing