hubspot-implementation-plan — Claude Code skill: audit planning

---
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. Works from a full, marketing, or sales audit report. Use after running /hubspot-audit, /hubspot-marketing-audit, or /hubspot-sales-audit."
license: MIT
metadata:
  author: tomgranot
  version: "2.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` (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:

| Scope | Report |
|-------|--------|
| full | `reports/hubspot-audit-*.md` |
| marketing | `reports/hubspot-marketing-audit-*.md` |
| sales | `reports/hubspot-sales-audit-*.md` |

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.

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

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

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.

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

| Task | Trigger (from audit) | Skill | Automation | Est. Time |
|------|----------------------|-------|------------|-----------|
| Reassign open deals from deactivated owners | Sales Ownership: orphaned open deals > 0 | `/reassign-deactivated-owners` | Fully scriptable | with Phase 1 |
| Assign unowned SQL / Opportunity contacts | Sales Ownership: unowned sales-stage contacts > 0 | `/assign-unowned-contacts` | Fully scriptable | 1-2 hrs |
| Fix past-due close dates and missing amounts | Deal Data Quality or Pipeline Hygiene graded C or worse | `/cleanup-deals` | Partially scriptable (needs rep input) | 2-4 hrs |
| Review and close stale deals | Pipeline Hygiene: stale open deals > 0 | `/cleanup-deals` | Partially scriptable (needs rep input) | 2-3 hrs |
| Retire empty or over-staged pipelines | Pipeline Configuration graded C or worse | `/cleanup-deals` | Manual UI | 1-2 hrs |
| Reconcile Opportunity contacts with no deal | Sales Ownership: Opportunity contacts with no deal > 0 | `/fix-lifecycle-stages` | Fully scriptable | 1-2 hrs |

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

| 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 audit (full, or scoped per team) | Quarterly | `/hubspot-audit`, `/hubspot-marketing-audit`, `/hubspot-sales-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 v4 Automation API (beta), 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 limits: 100 requests per 10 seconds per app on Free/Starter, 190 on Professional/Enterprise; the Search API is capped separately at 5 per second** — 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 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