Brainforge Knowledge

SCOPING_SUMMARY

6 min read

HubSpot Lead Nudge Agent - Scoping Summary

Purpose: High-level scoping document before building. Defines capabilities, constraints, and success criteria.
Date: 2026-02-17
Status: Scoping Complete - Ready for PRD Review

Problem Statement

Current State:

  • Deals stuck in same HubSpot deal stage for ~21 days average
  • No systematic follow-up on stalled deals
  • Follow-ups are ad-hoc, inconsistent, and often forgotten
  • No escalation strategy; deals stay stuck indefinitely

Desired State:

  • Deals move through stages faster (<10 days average)
  • Every stuck deal gets consistent, persistent follow-up
  • Clear escalation path (EA → Sales → Founder)
  • Context-aware personalization in every message

Key Learnings from McGaw Sequence (Refined)

What Worked:

  1. Persistent follow-up - Multiple touches eventually got response
  2. Different people - MC → Sarah → Dan escalation kept it fresh
  3. Booking links - Every message included booking links (not embedded calendars)
  4. Escalation to CEO - Dan’s direct message (“Text me if you want to knock this out ASAP”) was effective after 3 assistant touches
  5. Value-add angles - Blog post, resources, different approaches

What Didn’t Work:

  1. Broken booking links - Robert called out broken link (need to verify links work)
  2. Too many touches - 21 messages over 2 months was excessive
  3. Generic messaging - Some messages were too generic (“checking in”)
  4. Urgency manipulation - Never use “time is running out” or similar pressure tactics

Refined Approach:

  1. Touch frequency: First 3 touches every 5 days, then Touch 4-5 every 10 days, Touch 6+ once per month
  2. Escalation timing: 3 touches from assistant before CEO escalation (not 3+)
  3. Response handling: Meeting booking = ideal. Any response → HubSpot note with context for EA action. Executives only if EA uncertain.
  4. Never drop off: Monthly value-add touches (Touch 6+) with posts, case studies, Brainforge updates to stay top of mind
  5. No manipulation: Never use urgency language - it’s manipulative

Patterns to Apply:

  • Touch 1-2: Friendly, value-add, calendar link
  • Touch 3-4: Different angle, escalation hint, calendar link
  • Touch 5+: Direct ask, founder escalation, calendar link
  • Escalation: When 3+ touches with no response, escalate to founder

Agent Capabilities (Scoped)

✅ In Scope (MVP)

  1. HubSpot Integration

    • Query deals stuck >10 days in same stage
    • Fetch deal, contact, company context
    • Log nudge activities as notes
    • Track touch count and last nudge date

  2. Message Generation

    • Generate personalized nudge messages based on:
      • Deal context (company, amount, stage)
      • Touch count (1-3, 4-5, 6+)
      • Touch frequency rules (every 5 days, every 10 days, monthly)
    • Include booking links in every message (not embedded calendars)
    • Vary messaging angle by touch count
    • Never use urgency/manipulation language

  3. Response Handling

    • Ideal response = meeting booking
    • If response (but not meeting) → Create HubSpot note with summarized context for EA action
    • EA takes action based on HubSpot note
    • Only escalate to executives if EA uncertain about follow-up

  4. Escalation Logic

    • Touch 1-3: Assistant only (EA sends)
    • Touch 4+: CEO escalation (after 3 assistant touches with no response)
    • Touch 6+: Monthly value-add touches (posts, case studies, Brainforge updates)

  5. Daily Reporting

    • Generate daily nudge report with all stuck deals
    • Include generated messages for EA review
    • Include escalation suggestions

❌ Out of Scope (Future)

  1. Automated Sending

    • Agent drafts, EA reviews and sends (human-in-the-loop)
    • Future: Auto-send after EA approval

  2. Response Detection

    • EA manually logs responses
    • Future: Auto-detect email responses and update HubSpot

  3. Meeting Detection

    • EA manually logs meetings
    • Future: Auto-detect calendar bookings and update deal stage

  4. LinkedIn Integration

    • Email only for MVP
    • Future: LinkedIn message generation

  5. A/B Testing

    • Single message variant per touch count
    • Future: Test multiple angles and track performance

Technical Requirements

HubSpot API Access

Required:

  • HubSpot MCP configured (read operations)
  • HubSpot API service access (write operations)
  • Private app token with scopes:
    • crm.objects.deals.read
    • crm.objects.contacts.read
    • crm.objects.companies.read
    • crm.objects.notes.write
    • crm.objects.deals.write

Custom Properties:

  • nudge_touch_count (number)
  • nudge_last_date (date)
  • nudge_next_date (date) - Calculated next touch date based on frequency rules

Agent Tools

Required:

  • mcp_hubspot_search_crm_objects - Query deals
  • mcp_hubspot_get_crm_object - Fetch deal/contact/company details
  • Read / Write - File operations for reports

Future:

  • Email API integration (for auto-send)
  • Calendar API integration (for meeting detection)

Success Criteria

Primary Metrics

  1. Deal Stage Duration

    • Current: ~21 days average
    • Target: <10 days average
    • Measurement: Track days in stage per deal

  2. Follow-Up Coverage

    • Current: 0% (no systematic follow-up)
    • Target: 100% of stuck deals receive nudges
    • Measurement: % of deals stuck >10 days that get nudges

  3. Deal Stagnation

    • Current: Baseline TBD
    • Target: <10% of deals stuck >21 days
    • Measurement: % of deals in pipeline stuck >21 days

Secondary Metrics

  • Response rate by touch count
  • Meeting booking rate from nudges
  • Deal advancement rate (nudged deals → next stage)

Implementation Phases

Phase 1: MVP (Week 1-2)

Scope:

  • HubSpot query for stuck deals
  • Basic message generation (3-4 templates)
  • Daily report generation
  • Manual EA review and send

Deliverables:

  • Agent PRD ✅
  • HubSpot integration working
  • Message templates
  • Daily report format

Success Criteria:

  • Agent successfully queries HubSpot
  • Generates messages for EA review
  • EA can send messages and log in HubSpot

Phase 2: Enhancement (Week 3-4)

Scope:

  • Escalation logic
  • Touch count tracking
  • Message variation by touch count
  • Escalation message variants

Deliverables:

  • Escalation rules implemented
  • Touch count tracking in HubSpot
  • 6+ message templates (by touch count)

Success Criteria:

  • Escalation suggestions work
  • Touch count accurately tracked
  • Messages vary appropriately

Phase 3: Learning & Optimization (Week 5+)

Scope:

  • Response tracking
  • Performance analysis
  • Message optimization
  • A/B testing (future)

Deliverables:

  • Response rate tracking
  • Performance dashboard
  • Optimized message templates

Success Criteria:

  • Can measure what works
  • Messages improve over time
  • Deal stage duration decreases

Risks & Mitigations

RiskMitigation
HubSpot API rate limitsBatch queries, cache results, respect rate limits
Message qualityHuman-in-the-loop review (EA approves all messages)
Over-nudgingCap touch count, respect “do not contact” flags
Broken calendar linksVerify links before including, test regularly
Escalation timingClear rules (Touch 3+, 21+ days), EA discretion
Context accuracyPull fresh data from HubSpot, don’t cache stale context

Dependencies

  1. HubSpot Integration

    • HubSpot MCP configured ✅
    • HubSpot API service access ✅
    • Custom properties created (need to create)

  2. Booking Links

    • EA booking link (need to configure)
    • Founder booking link (need to configure)
    • Verify links work before including in messages

  3. Message Templates

    • Base templates from McGaw sequence ✅
    • Need to adapt for Brainforge context

  4. EA Workflow

    • EA review process (need to define)
    • EA send process (need to define)
    • EA logging process (need to define)

Next Steps

  1. Review PRD - Review PRD.md for completeness and accuracy
  2. Create HubSpot Custom Properties - Add nudge_touch_count and nudge_last_date
  3. Configure Calendar Links - Set up EA and founder calendar links
  4. Build MVP - Start with Phase 1 (basic query + message generation)
  5. Test with EA - Run daily reports, EA reviews and sends
  6. Iterate - Based on EA feedback and response rates

Questions to Resolve

  1. Calendar Links: What calendar tool? (Mixmax, Calendly, other?)
  2. EA Workflow: How does EA want to receive reports? (Slack, email, dashboard?)
  3. Touch Count: How to track? (HubSpot custom property, notes, activities?)
  4. Escalation: Who escalates? (EA coordinates, or agent auto-escalates?)
  5. Response Tracking: Manual or automated? (EA logs, or agent detects?)

Status: Scoping complete - Ready for PRD review and build planning
Owner: TBD
EA Owner: TBD

Graph View