<aside> 🛠️

This proposal extends the counselors review with a concrete automation plan. It leverages existing infrastructure in the Commission Consolidator app (cohort ramp curves, onboarding audit, health scoring, HubSpot integration) to build real-time risk tagging, automated gates, and dependency tracking for the onboarding process.

</aside>

The Core Idea

Treat onboarding like a CI/CD pipeline. Every account has a dependency graph with gates. Gates don't pass until prerequisites are met. When gates stall, the system escalates automatically — no human has to remember to follow up.

What Already Exists (Commission Consolidator)

Before building anything new, here's what the app already tracks:

Capability	What It Does	Where It Lives
Cohort Classification	Groups clients by vertical × tier (4-level fallback: exact → vertical → tier → global). Min cohort sizes enforced.	`launchRamp.js`, `constants.js`
Ramp Curves	Data-driven 12-month revenue ramp per cohort. Median of months 9-11 = stabilized MRR. Default: 10% → 25% → 50% → 75% → 90% → 100%.	`launchRamp.js`, `forecasting.js`
Onboarding Audit	Tracks every change to `expected_launch_date` from HubSpot property history. Computes drift, slip days, volatility. Append-only audit trail.	`OnboardingAuditView.jsx`, `onboardingAuditCapture.js`, `expected_launch_date_audit` table
Health Scoring	8-tier classification (churned → volume variance → at-risk → watch → new → declining → growing → stable). Revenue-weighted thresholds. Pre-launch guard prevents false alarms.	`healthCalculations.js`
Contract Lifecycle	4 phases: pre_effective → pre_launch → post_launch → churned. Tracks signed_date → effective_date → launch_date → end_date.	`contractLifecycle.js`, `contracts.js`
Time-to-Value	Days from effective_date to launch_date. Median & P75 computed. Color-coded: ≤30d green, ≤60d amber, >60d red.	`contracts.js`, `peMetrics.js`
HubSpot Integration	Deal stages (Discovery → Sandbox → Go-Live Readiness → Launched), deal-to-client mapping, communication health cache (meetings/calls/emails/tickets with 30/60/90/365-day counts).	`server.js`, `hubspot_comm_health_cache` table
Implementation Alpha	Unrealized revenue from pre-launch clients: estimatedACV - currentBilling. Tracks "trapped ARR" during onboarding.	`peMetrics.js`

What Needs to Be Built

1. Account Complexity Scoring (Auto-Tag at Contract Signature)

When a deal closes in HubSpot, automatically classify the account into a complexity tier using data already available:

Signal	Source	Standard	Moderate	Complex
Entity count	HubSpot deal / sales handoff	1 entity	2-5 entities	6+ entities (Gurstel = 70+)
Platform tier	contracts.platform_type	Pro	Enterprise	Enterprise Plus
SMS required	HubSpot deal property	No	Yes (single shortcode)	Yes (multiple shortcodes)
Merchant accounts	HubSpot deal / sales handoff	1 standard	2-5 accounts	6+ or trust/IOLTA
CMS platform	Sales handoff	Known CMS with playbook	Known CMS, no playbook	Unknown/custom CMS
Cohort ramp history	launchRamp.js cohort profiles	Cohort median TTV ≤45d	Cohort median TTV 45-75d	Cohort median TTV >75d

Output: Each new contract gets a complexity_tier field (standard / moderate / complex) that determines:

Target timeline (30-45 / 45-60 / 60-90 days)
Session cadence (2x/week / 2x/week + weekly exec check / 3x/week)
Staffing (1 CSM / 1 CSM + solutions engineer / dedicated team)
Gate deadlines (aggressive / standard / extended)

How it connects: The cohort ramp profiles already tell you how long similar accounts took. If the cohort median TTV for debt buyer::enterprise is 78 days, don't promise 30. The system should surface this automatically when the deal closes.