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.0"
  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:** 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:

```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

| 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