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	INLINECODE4	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. 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	INLINECODE12	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)	INLINECODE18	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	INLINECODE22	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. 1. Manual UI Build -- Follow the step-by-step instructions in each skill. Most reliable, full control over triggers and actions.

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

1. 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	INLINECODE31	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:

CODEBLOCK0

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

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

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

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

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

CODEBLOCK1text
[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 │
CODEBLOCK2

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. 1. Flag it in the plan: Add a section called "Custom Skills Needed" listing each gap.

1. 2. Offer to create the skill:

CODEBLOCK3

1. 3. Ask about upstream contribution:

CODEBLOCK4

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

CODEBLOCK5

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