hubspot-implementation-plan

name	hubspot-implementation-plan
description	Generate a phased implementation plan from a HubSpot audit report. Creates prioritized, sequenced cleanup processes with effort estimates, dependencies, and automation feasibility. Use after running /hubspot-audit.
license	MIT
metadata	{"author":"tomgranot","version":"1.1","category":"audit-planning"}

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: Configuring lead scoring rules is still UI-only (the post-2025 scoring tool has no configuration API), but 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.

Task	Trigger (from audit)	Skill	Automation	Est. Time
New contact hygiene workflow	Always	/new-contact-hygiene-workflow	Hybrid (API + UI review)	1-2 hrs
Engagement-based suppression workflow	Engagement grade D or F	/engagement-suppression-workflow	Hybrid (API + UI review)	1-2 hrs
Lifecycle stage progression workflow	Always	/lifecycle-progression-workflow	Hybrid (API + UI review)	1-2 hrs
Bounce monitoring workflow	Deliverability grade C or worse	/bounce-monitoring-workflow	Hybrid (API + UI review)	1 hr
Export workflows as versioned JSON	After any workflow build	/workflows-as-code	Fully scriptable	30 min

Key update: The v4 Automation API is stable and 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.

2. 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.

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. Workflows are created via the stable v4 Automation API, always disabled — Scripts create every workflow with isEnabled: false; a human reviews it in the UI before enabling. UI-only leftovers: copy-from-associated-object actions and notification recipients (undocumented API field shapes). The v3 workflows API is legacy — do not build new integrations on it.

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 created via v4 API, always disabled for UI review ...
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