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)
• 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.

Task	Trigger (from audit)	Skill	Automation	Est. Time
Delete contacts with no email address	Data Completeness: missing email count > 0	/delete-no-email-contacts	Fully scriptable	1 hr
Suppress hard bounced contacts	Deliverability: hard bounce count > 0	/suppress-hard-bounced	Hybrid (API + workflow)	1-2 hrs
Suppress global unsubscribes	Deliverability: global unsub count > 0	/suppress-global-unsubscribes	Hybrid (API + workflow)	1-2 hrs
Suppress ghost contacts (never engaged)	Engagement: never-engaged count > threshold	/suppress-ghost-contacts	Hybrid (API + workflow)	2-3 hrs
Merge duplicate companies	Duplicates: duplicate domain count > 0	/merge-duplicate-companies	Fully scriptable	2-4 hrs
Reassign deactivated owner contacts	Owner Health: deactivated owners with records > 0	/reassign-deactivated-owners	Fully scriptable	1-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.

Task	Trigger (from audit)	Skill	Automation	Est. Time
Enrich company name from association	Completeness: missing company name	/enrich-company-name	Fully scriptable	1-2 hrs
Enrich contact industry from company	Completeness: missing industry	/enrich-industry	Fully scriptable	1-2 hrs
Standardize country/state values	Completeness: inconsistent geo data	/standardize-geo-values	Fully scriptable	2-3 hrs
Backfill country/state from IP or company	Completeness: missing geo data	/backfill-geo-data	Fully scriptable	2-3 hrs
Fix lifecycle stages	Completeness: missing or incorrect lifecycle stages	/fix-lifecycle-stages	Fully scriptable	2-3 hrs
Assign unowned contacts	Owner Health: unowned contacts > 0	/assign-unowned-contacts	Fully scriptable	1-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.

Task	Trigger (from audit)	Skill	Automation	Est. Time
Create ICP tier property and workflows	Always (after enrichment)	/create-icp-tiers	Hybrid (API + workflow)	3-4 hrs
Build lead scoring model	Always (after enrichment)	/build-lead-scoring	Manual UI only	4-6 hrs
Build smart lists for segments	Always (after scoring)	/build-smart-lists	Fully scriptable (Lists API)	2-3 hrs
Create segment lists for campaigns	Always (after smart lists)	/create-segment-lists	Fully scriptable	1-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.

Task	Trigger (from audit)	Skill	Automation	Est. Time
New contact hygiene workflow	Always	/new-contact-hygiene-workflow	Manual UI only	2-3 hrs
Engagement-based suppression workflow	Engagement grade D or F	/engagement-suppression-workflow	Manual UI only	2-3 hrs
Lifecycle stage progression workflow	Always	/lifecycle-progression-workflow	Manual UI only	2-3 hrs
Bounce monitoring workflow	Deliverability grade C or worse	/bounce-monitoring-workflow	Manual UI only	1-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.

Task	Frequency	Skill	Automation	Est. Time
Weekly cleanup routine	Weekly	/weekly-cleanup-routine	Checklist (manual)	1 hr/week
Clean up unused lists	Monthly	/cleanup-lists	Partially scriptable	1-2 hrs
Clean up unused forms	Monthly	/cleanup-forms	Partially scriptable	1-2 hrs
Clean up stale workflows	Monthly	/cleanup-workflows	Partially scriptable	1-2 hrs
Clean up dashboards	Quarterly	/cleanup-dashboards	Manual UI only	1-2 hrs
Clean up stale deals	Quarterly	/cleanup-deals	Partially scriptable	2-3 hrs
Clean up unused properties	Quarterly	/cleanup-properties	Partially scriptable	2-3 hrs
Review lead owners	Quarterly	/cleanup-lead-owners	Partially scriptable	1-2 hrs
Review bounced contacts	Monthly	/review-bounced-contacts	Partially scriptable	1 hr
Quarterly full database audit	Quarterly	/hubspot-audit	Fully scriptable	1 hr

3. Build the Dependency Graph

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

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:

Category	Hours
Fully scriptable tasks	X hrs
Hybrid tasks (API + manual workflow)	X hrs
Manual UI tasks	X hrs
Total 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:

# 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

Category	Tasks	Hours
Fully scriptable	X	XX hrs
Hybrid (API + workflow)	X	XX hrs
Manual UI only	X	XX hrs
Ongoing maintenance	X	XX hrs/month
Total initial setup	X	XX 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

### 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?

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.

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