deal-momentum-analyzer

What this skill does

<objective>
Score every open deal on momentum (not just stage) using multi-signal analysis: days in stage, activity recency, stakeholder engagement, call/activity sentiment, and MEDDIC completeness. Surfaces the 3-5 deals most likely to slip and prescribes specific next-best-actions to recover them. Target: recover 5-10% of stalled pipeline monthly (~$18K/mo at current pipeline levels).
</objective>

<quick_start>
**Daily automated run (7am CST):**
Scheduled task pulls all open deals → scores momentum → delivers prioritized action list

**On-demand:**
"deal momentum" → runs full analysis now
"pipeline review" → same, formatted as pipeline review
"which deals need attention" → filtered to at-risk only

**Trigger phrases:**
- "deal health" / "deal momentum"
- "pipeline review" / "stalled deals"
- "which deals need attention"
- "morning brief" / "SOD" (integrates into daily brief)
</quick_start>

<success_criteria>
- Every open deal scored 0-100 on momentum
- Deals classified: GREEN (on-track), YELLOW (slowing), RED (stalled)
- Top 3-5 at-risk deals surfaced with specific next-best-action
- Weekly trend: are deals accelerating or decelerating?
- Target: recover 5-10% of stalled deals per month via timely intervention
- Zero false negatives on deals about to slip close date
</success_criteria>

<workflow>

## Architecture

```
SCHEDULED (7am CST)          ANALYSIS                    OUTPUT
─────────────────────────────────────────────────────────────────
HubSpot: all open deals  →  Score each deal on     →  Prioritized dashboard
CRM: activity history    →  6 momentum signals     →  Next-best-action per deal
Activity: emails/calls   →  Classify G/Y/R         →  Gmail draft (optional)
                          →  Compare to last run    →  Calendar blocks (optional)
```

## Stage 1: Data Collection

### 1a. Pull All Open Deals (Owner OR Collaborator)
Use `search_crm_objects` (HubSpot MCP) with **two OR-ed filter groups** to capture both owned and collaborated deals:

**FilterGroup 1 — Tim is COLLABORATOR:**
- `hs_all_collaborator_owner_ids` CONTAINS_TOKEN `87486452`
- `hs_is_closed` EQ `false`

**FilterGroup 2 — Tim is OWNER:**
- `hubspot_owner_id` EQ `87486452`
- `hs_is_closed` EQ `false`

**Properties to request:**
`dealname`, `dealstage`, `amount`, `hubspot_owner_id`, `hs_lastmodifieddate`, `notes_last_updated`, `closedate`, `pipeline`, `createdate`, `hs_all_collaborator_owner_ids`, `num_associated_contacts`, `hs_deal_stage_probability`

Sort by `hs_lastmodifieddate` DESCENDING. Limit 100.

For each deal, capture:
| Field | HubSpot Property |
|-------|-----------------|
| Deal name | `dealname` |
| Amount | `amount` |
| Stage | `dealstage` |
| Close date | `closedate` |
| Create date | `createdate` |
| Last activity | `notes_last_updated` or `hs_lastmodifieddate` |
| Owner | `hubspot_owner_id` |
| Collaborators | `hs_all_collaborator_owner_ids` |
| Associated contacts | via associations |
| Associated company | via associations |

### 1a-bis. Deal Role Tagging
After pulling deals, tag each deal with Tim's role:
- **OWNER** — `hubspot_owner_id` = `87486452` → Tim owns the deal directly
- **COLLABORATOR** — `hs_all_collaborator_owner_ids` contains `87486452` but `hubspot_owner_id` ≠ `87486452` → Tim is helping close (AE-owned or SE-owned deal)

**Display both types** in the momentum report. Collaborator deals where an AE owns them (owner IDs 82625923 Lex Evans, 423155215 Ron Epstein, 190030668 Phillip Sandler) are deals Tim sourced or is actively supporting — they ARE his pipeline contribution and must be tracked.

**Exclude from scoring** only deals where Tim is NEITHER owner NOR collaborator (i.e., deals that somehow appeared but have no Tim involvement).

### 1b. Clari Call Intelligence (Signal 4 Data Source)

Pull recent Clari call data for contacts associated with each deal:

| Tool | Purpose |
|------|---------|
| `clari_search_calls` | Find calls involving deal contacts (filter by attendeeEmail, last 30 days) |
| `clari_get_call_summary` | Get AI summary + action items for each relevant call |

For each deal's associated contacts:
1. Search Clari calls: `clari_search_calls(attendeeEmail=contact_email, daysBack=30)`
2. For calls found: `clari_get_call_summary(callId=call_id)` 
3. Extract:
   - **Call sentiment**: positive/neutral/negative from AI summary
   - **Discovery completeness**: were MEDDIC questions asked?
   - **Competitor mentions**: any competitor names in summary
   - **Action items**: unresolved action items = stall risk
   - **Last call date**: recency signal for Signal 4 scoring

**Signal 4 Enhancement (Call Momentum — 15 points):**
| Sub-signal | Points | Criteria |
|-----------|--------|----------|
| Clari call in last 7 days | 5 | Recent engagement confirmed |
| Positive sentiment | 4 | AI summary = positive/constructive |
| MEDDIC questions asked | 3 | Discovery topics covered in transcript |
| No unresolved action items | 2 | All action items closed |
| No competitor mentions | 1 | Clean competitive position |

If no Clari data found, fall back to HubSpot activity recency (existing logic). Never score 0 just because Clari is empty.

### 1c. Pull Activity History
For each deal's associated company, use `ask_agent`:
- Query: "Show all activity, notes, and engagement for [company] deals in last 30 days"
- Extracts: call notes, email activity, meeting outcomes, deal stage changes

### 1c. Pull Contact Engagement
For each deal's associated contacts, use `hubspot_search_contacts`:
- Last email open/click dates
- Form submissions
- Page views
- Meeting bookings

## Stage 2: Momentum Scoring (0-100)

Score each deal on 6 weighted signals:

### Signal 1: Days in Current Stage (25 points)
| Condition | Points |
|-----------|--------|
| < median for this stage | 25 |
| At median | 15 |
| 1.5x median | 8 |
| > 2x median | 0 |

Stage medians (calibrate from Tim's historical data):
| Stage | Expected Days |
|-------|--------------|
| Appointment Scheduled | 7 |
| Qualified to Buy | 14 |
| Presentation Scheduled | 10 |
| Decision Maker Bought-In | 14 |
| Contract Sent | 7 |
| Closed Won | — |

### Signal 2: Activity Recency (20 points)
| Last activity | Points |
|--------------|--------|
| < 3 days ago | 20 |
| 3-7 days | 15 |
| 7-14 days | 8 |
| 14-21 days | 3 |
| > 21 days | 0 |

### Signal 3: Stakeholder Breadth (15 points)
**ATL/BTL Validation Required (see CLAUDE.md § ATL/BTL Classification v1.0):**
For each deal's associated contacts, classify by title before scoring:
- **ATL:** Chief, VP, Director, Dean, Provost, Superintendent, Court Administrator, City Manager, Senior Pastor, Executive Pastor
- **GRAY:** Manager (AV/Facilities/IT) — only counts as ATL-equivalent if confirmed budget >$25K
- **BTL:** Technician, Specialist, Coordinator, Support, Administrator (Systems/Network/Database), Engineer, Operator, Instructor/Faculty, Designer, Assistant, Clerk (non-Court Admin), Volunteer, Intern, Student, Resident, Help Desk
- **NEVER ATL:** Warehouse Manager, Network Manager, Systems Administrator, AV Technician, Graphic Design Instructor, Program Administrator, Web Designer, Classroom Support, Lab Coordinator, Maintenance, Building Engineer, Multimedia Services Manager, Video Production Specialist, Streaming Crew

| Contacts engaged | Points |
|-----------------|--------|
| 3+ contacts, including at least 1 ATL-tier contact (confirmed EB) | 15 |
| 2+ contacts with at least 1 ATL-tier | 12 |
| 2+ contacts but ALL are BTL/GRAY (no confirmed ATL) | 7 |
| 1 contact (champion only, regardless of tier) | 5 |
| 1+ contacts but ALL are NEVER ATL titles | 2 |
| 0 active contacts | 0 |

**Penalty flag:** If a deal has 0 ATL-tier contacts, add a ⚠️ flag in the report: "NO ECONOMIC BUYER IDENTIFIED — deal at risk of stalling at Decision Maker stage. Action: ask champion to intro Director+/VP+."

### Signal 4: Call Momentum (15 points)
Uses Clari call data as primary signal source (see Stage 1b: Clari Call Intelligence).

| Activity signal | Points |
|