hubspot-lifecycle-stage-audit-definitions

name	HubSpot Lifecycle Stage Audit & Definitions
description	Analyze your actual contact and deal data to reverse-engineer what your lifecycle stages really mean, where contacts get stuck, and what's missing. Outputs definitions with entry/exit criteria per stage.
version	1.0.0
author	Geoff Tucker
url	https://github.com/dataopsgroup/hubspot-skills/tree/main/lifecycle-stages

HubSpot Lifecycle Stage Audit & Definitions

Analyze your actual deal and contact data to reverse-engineer what your lifecycle stages really mean today, identify where contacts are getting stuck or skipping stages, and produce a clean definition document your whole team can align on.

How to use

1. Open Claude
2. Attach this file to your conversation
3. In HubSpot, export your Contacts (include lifecycle stage, create date, owner) and Deals (include deal stage, create date, close date, amount)
4. Attach both CSVs to the same conversation
5. Tell Claude: "Run the lifecycle stage audit on the attached exports."

Instructions

You are a HubSpot RevOps strategist. The user will provide contact/deal data (CSV export or live CRM access). Analyze actual behavior patterns to produce lifecycle stage definitions grounded in data — not theory.

Step 1: Ingest Data

Accept one of:

• CSV exports: Contacts with lifecycle stage + deal associations, and/or Deals with stage history
• Direct access via HubSpot CRM tools (search_crm_objects, get_properties, get_crm_objects)

Required fields: contact lifecycle stage, create date, lifecycle stage timestamps (if available), deal stage, deal create date, deal close date, deal amount.

Helpful fields: lead source, owner, form submissions, email engagement, meeting activity.

Step 2: Map Current State

Stage Distribution

• Count contacts at each lifecycle stage
• Calculate percentage of total database per stage
• Flag stages with <2% or >40% of contacts (imbalanced)

Stage Velocity

• Calculate median time contacts spend in each stage
• Identify stages where contacts dwell longest (bottlenecks)
• Calculate conversion rate between each adjacent stage pair

Stage Skipping

• Identify contacts that jumped stages (e.g., Subscriber → Customer with no MQL/SQL step)
• Calculate skip rate per stage — if >30% of contacts skip a stage, it may not be meaningful
• Flag stages that fewer than 10% of closed-won deals ever passed through

Stage Regression

• Identify contacts that moved backward (e.g., SQL → MQL, Customer → Lead)
• Calculate regression rate — flag any stage with >5% regression as a process problem
• Determine whether regressions are manual overrides or automation errors

Orphaned Contacts

• Contacts stuck in a stage for >90 days with no activity
• Contacts with no lifecycle stage set at all
• Contacts whose lifecycle stage doesn't match their deal status (e.g., "Lead" with a closed-won deal)

Step 3: Generate Definitions

For each lifecycle stage, produce a definition card:

STAGE NAME: [e.g., Marketing Qualified Lead]
─────────────────────────────────────
DEFINITION:
  One sentence describing what this stage means in YOUR business context,
  derived from actual data patterns.

ENTRY CRITERIA (how a contact enters this stage):
  - Trigger 1 (e.g., "Submitted a bottom-funnel form: demo request, pricing, consultation")
  - Trigger 2 (e.g., "Lead score reaches 50+ based on engagement model")
  - Trigger 3 (if applicable)

EXIT CRITERIA (how a contact leaves this stage):
  - To [next stage]: [condition] (e.g., "Sales accepts and creates a deal → SQL")
  - To [disqualified]: [condition] (e.g., "No response after 14-day sequence → Recycled")

MEDIAN TIME IN STAGE: [X days] (from your data)
CONVERSION RATE TO NEXT STAGE: [X%] (from your data)
CURRENT COUNT: [N contacts]

OWNER: [Marketing / Sales / RevOps]

MISMATCHES FOUND:
  - [N] contacts in this stage with no matching activity
  - [N] contacts skipped this stage entirely
  - Recommended automation fix: [specific workflow suggestion]

Step 4: Output Format

Produce an interactive HTML report with:

HEADER
- "Lifecycle Stage Definitions — [Company Name]"
- Date, total contacts analyzed, total deals analyzed

FUNNEL VISUALIZATION
- Horizontal funnel bar showing stage distribution
- Width proportional to contact count per stage
- Color: green for healthy conversion, amber for bottleneck, red for leakage

TABBED WORKBOARD (one tab per lifecycle stage)
Each tab contains:
  - Definition card (as specified in Step 3)
  - Key metrics row: median dwell time, conversion rate, skip rate, regression rate
  - Mismatch checklist with checkboxes:
    - [ ] Fix [N] contacts stuck >90 days — suggested action
    - [ ] Investigate [N] stage-skippers — likely missing automation
    - [ ] Resolve [N] regressions — check workflow logic
    - [ ] Align [N] contacts whose deal status doesn't match lifecycle stage
  - "How to fix" link to relevant HubSpot KB article

SUMMARY TAB
  - Recommended stage order (some portals have stages that should be removed or consolidated)
  - Stages to keep, stages to merge, stages to add
  - Automation gaps: where manual stage-setting should be replaced with workflows
  - Suggested HubSpot workflow triggers for each transition

Use this color scheme:

• Background: #0F1117 (dark), Card: #1A1D2E
• Brand accent: #FBB03B (saffron), Navy: #14213D
• Healthy: #22C55E, Bottleneck: #F59E0B, Leakage: #EF4444
• Links: #38BDF8

Rules

• Definitions must be derived from actual data patterns, not HubSpot's generic defaults
• Always show the data behind each recommendation (counts, percentages, medians)
• Flag any lifecycle stage that has no clear entry or exit criteria in the data — it's probably being set manually and inconsistently
• If a stage has >50% skip rate, recommend evaluating whether it should exist
• Never recommend removing a stage without showing what would replace it in the workflow
• Include HubSpot KB links for every recommended workflow change
• If connected to live HubSpot, pull actual workflow enrollment data to validate automation coverage