@microsoft/next-best-action-engine

---
name: next-best-action-engine
description: Analyzes an opportunity's current state and engagement history, compares against won deals, and recommends the most effective next action with reasoning. Use when user asks "what should I do next on this deal", "next steps for this opportunity", "how do I move this deal forward", "what's the best action for this opp", "deal coaching", or "opportunity next action".
metadata:
  author: Dataverse
  version: 1.0.0
  category: sales-coaching
---

# Next Best Action Engine

Sales reps often wonder "What should I do next on this deal?" This skill provides data-driven recommendations by analyzing the current opportunity state and comparing it to successful deals at the same stage, identifying what actions led to wins and recommending the most impactful next step.

## Instructions

### Step 1: Retrieve Opportunity Context
When user asks "What should I do next on the [Opportunity Name] opportunity?":

**1.1 Get Opportunity Details:**
```
SELECT opportunityid, name, customerid, accountid, contactid, estimatedvalue,
       estimatedclosedate, salesstage, stepname, closeprobability,
       budgetstatus, need, purchasetimeframe, purchaseprocess, decisionmaker,
       description, currentsituation, customerneed, customerpainpoints,
       proposedsolution, msdyn_opportunityscore, msdyn_forecastcategory,
       createdon, modifiedon, ownerid, statecode
FROM opportunity
WHERE opportunityid = '[opportunity_id]'
```

**1.2 Get Account Information:**
```
SELECT accountid, name, industrycode, numberofemployees, revenue,
       telephone1, emailaddress1, websiteurl, primarycontactid
FROM account
WHERE accountid = '[accountid from opportunity]'
```

**1.3 Get Related Contacts:**
```
SELECT contactid, fullname, jobtitle, emailaddress1, telephone1,
       accountrolecode, msdyn_decisioninfluencetag
FROM contact
WHERE accountid = '[accountid]'
```

#### Step 2: Analyze Activity History

**2.1 Get All Activities:**
```
SELECT activityid, activitytypecode, subject, description,
       createdon, actualstart, actualend, statecode, statuscode,
       prioritycode, ownerid
FROM activitypointer
WHERE regardingobjectid = '[opportunityid]'
ORDER BY createdon DESC
```

**2.2 Categorize Activities:**

| Activity Type | Code | Engagement Level |
|---------------|------|------------------|
| Meeting/Appointment | appointment | High |
| Phone Call | phonecall | High |
| Email | email | Medium |
| Task | task | Low (internal) |

**2.3 Calculate Engagement Metrics:**
```
Activity Summary:
- Total Activities: [count]
- Last 30 Days: [count]
- Activity Types: [breakdown]
- Last Activity: [date and type]
- Days Since Last Activity: [N]

Engagement Trend:
- Week 1: [count]
- Week 2: [count]
- Week 3: [count]
- Week 4: [count]
- Trend: [Increasing/Stable/Declining]
```

**2.4 Analyze Activity Content:**
Look for key themes in activity descriptions and subjects:
- Competitor mentions
- Objection indicators
- Positive signals ("interested", "excited", "moving forward")
- Negative signals ("concern", "budget freeze", "competitor")
- Stakeholder engagement (who was involved)

#### Step 3: Assess Stakeholder Engagement

**3.1 Map Stakeholder Involvement:**
```
For each contact at the account, determine:
- Last interaction date
- Interaction count
- Role (Decision Maker, Influencer, Champion, Blocker, User)
- Engagement level (High/Medium/Low/None)
```

**3.2 Identify Stakeholder Gaps:**
```
Check for missing stakeholder engagement:
- Economic Buyer (C-level/VP): [Engaged? Y/N]
- Technical Evaluator: [Engaged? Y/N]
- End User: [Engaged? Y/N]
- Procurement: [Engaged? Y/N] (for late-stage deals)
- Champion: [Identified? Y/N]

Recommended stakeholders to engage: [List]
```

**3.3 Analyze Contact Roles:**
```
SELECT c.contactid, c.fullname, c.jobtitle, c.accountrolecode,
       c.msdyn_decisioninfluencetag
FROM contact c
WHERE c.accountid = '[accountid]'
```

Map job titles to buying roles:
- CEO, CFO, VP → Economic Buyer
- Director, Manager → Influencer/Champion
- Engineer, Analyst → Technical Evaluator/User

#### Step 4: Find Similar Won Opportunities

**Important: Dataverse SQL Limitations**
Dataverse SQL does NOT support: subqueries, DATEADD(), GETUTCDATE(), HAVING, DISTINCT, UNION, CASE.
Calculate date filters programmatically (e.g., '2024-03-01' for 2 years ago).

**4.1 Query Successful Deals:**
```
SELECT opportunityid, name, accountid, estimatedvalue, actualvalue,
       salesstage, actualclosedate, createdon,
       budgetstatus, need, purchasetimeframe
FROM opportunity
WHERE statecode = 1
AND actualclosedate > '2024-03-01'
```

To get industry from related account, use a JOIN:
```
SELECT o.opportunityid, o.name, o.estimatedvalue, a.industrycode, a.numberofemployees
FROM opportunity o
JOIN account a ON o.accountid = a.accountid
WHERE o.statecode = 1
AND o.actualclosedate > '2024-03-01'
```

**4.2 Define Similarity Criteria:**
| Factor | Weight | Matching Logic |
|--------|--------|----------------|
| Deal Size | 25% | Similar estimated value (±30%) |
| Industry | 20% | Same industry code |
| Sales Stage | 20% | Currently in same stage |
| Company Size | 15% | Similar employee count |
| Qualification | 20% | Similar BANT profile |

**4.3 Score Similarity:**
For each won deal, calculate similarity to current opportunity:
```
similarity_score = (
  size_match_score * 0.25 +
  industry_match_score * 0.20 +
  stage_match_score * 0.20 +
  company_match_score * 0.15 +
  qualification_match_score * 0.20
)
```

Select top 5-10 most similar won opportunities.

#### Step 5: Analyze Winning Patterns

**5.1 Activity Pattern Analysis:**
For each similar won deal, get activity history:
```
SELECT activitytypecode, COUNT(*) as count, 
       MIN(createdon) as first_activity,
       MAX(createdon) as last_activity
FROM activitypointer
WHERE regardingobjectid = '[won_opportunity_id]'
GROUP BY activitytypecode
```

**5.2 Identify Stage-Specific Success Actions:**
For deals that were in the same stage:
```
Calculate for each similar won deal at this stage:
- What activity type came next?
- How long did they spend in this stage?
- What was the outcome?
- Which stakeholders were engaged?
```

**5.3 Build Action Recommendations:**
Aggregate patterns from successful deals:
```
When similar deals were in [Current Stage]:
- 75% had a demo/presentation next
- 60% engaged the economic buyer
- 50% sent a proposal within 2 weeks
- Average time in stage: 14 days
```

#### Step 6: Generate Recommendations

**6.1 Primary Recommendation Engine:**

Based on opportunity state and winning patterns, recommend:

**If Stage = Qualify:**
```
Priority Actions:
1. Complete qualification (BANT gaps identified)
2. Identify and engage decision maker
3. Schedule discovery meeting
4. Understand competitive landscape
```

**If Stage = Develop:**
```
Priority Actions:
1. Demonstrate product/solution fit
2. Expand stakeholder map
3. Address technical requirements
4. Build internal champion
```

**If Stage = Propose:**
```
Priority Actions:
1. Present formal proposal
2. Handle objections
3. Engage procurement/legal
4. Negotiate terms
```

**If Stage = Close:**
```
Priority Actions:
1. Finalize contract details
2. Get verbal commitment
3. Process signatures
4. Address last-minute concerns
```

**6.2 Specific Action Recommendation:**

Based on analysis, provide ONE primary next action:

```
NEXT BEST ACTION RECOMMENDATION
════════════════════════════════════════════════════

OPPORTUNITY: [Name]
CURRENT STAGE: [Stage]
TIME IN STAGE: [X days]
HEALTH SCORE: [X/100]

════════════════════════════════════════════════════
RECOMMENDED NEXT ACTION
════════════════════════════════════════════════════

📌 [SPECIFIC ACTION]

Example: "Schedule a meeting with Sarah Chen (VP Operations) to present ROI analysis"

WHY THIS ACTION:
• Similar won deals had [X% higher close rate] when economic buyer was engaged at this stage
• Sarah Chen is the VP Operations and likely economic buyer (not yet engaged)
• You've had 4 interactions with technical team but none with leadership
• Competitive intelligence suggests prospect is evaluating alternatives

WHAT SUCCESSFUL DEALS DID:
• 78% of similar won deals engaged executive sponsor before Propose stage
• Average of 2.3 executive meetings before close
• Deals with VP+ engagement closed 40% faster

HOW TO EXECUTE:
1. Ask your champion [Contact Name] for an introduction to Sarah Chen
2. Prepare executive-level ROI summary (attach template)
3. Propose 30-minute business value discussion
4. Bring in your sales leader for executive alignment

TALKING POINTS:
• Business outcomes achieved by [Similar Customer in same industry]
• ROI: [X]% improvement in [metric] over [timeframe]
• Risk of inaction: [competitive/market pressure point]

SUGGESTED TIMELINE:
• Reach out to champion: Today
• Executive meeting: Within 1 week
• This will enable: Moving to [Next Stage] in 2 weeks
```

**6.3 Alternative Actions:**
```
ALTERNATIVE ACTIONS (if primary not feasible):
════════════════════════════════════════════════════

Option B: Schedule Technical Deep-Dive
• If champion unavailable, continue building technical consensus
• Request meeting with IT/Engineering stakeholders
• Demonstrate integration capabilities

Option C: Send Case Study
• If scheduling difficult, send relevant customer success story
• Focus on [Industry] case study showing [specific outcome]
• Request follow-up call to discuss applicability
```

#### Step 7: Create Activity Record

Offer to create the recommended activity:

**If Recommending a Meeting:**
```
Use create_record with tablename: appointment
{
  "subject": "[Generated meeting subject]",
  "description": "[Context and talking points]",
  "regardingobjectid": "[opportunityid]",
  "scheduledstart": "[suggested datetime]",
  "scheduledend": "[end datetime]",
  "requiredattendees": "[contact ids]",
  "location": "[virtual/in-person]"
}
```

**If Recommending a Call:**
```
Use create_record with tablename: phonecall
{
  "subject": "[Generated call subject]",
  "description": "[Context and talking points]",
  "regardingobjectid": "[opportunityid]",
  "phonenumber": "[contact phone]",
  "to": "[contact id]",
  "scheduledstart": "[suggested datetime]"
}
```

**If Recommending a Task:**
```
Use create_record with tablename: task
{
  "subject": "[Task description]",
  "description": "[Details and context]",
  "regardingobjectid": "[opportunityid]",
  "scheduledend": "[due date]",
  "prioritycode": 2
}
```

### Output Format Summary

```
════════════════════════════════════════════════════
NEXT BEST ACTION ANALYSIS: [Opportunity Name]
════════════════════════════════════════════════════

CURRENT STATE:
• Stage: [Stage]
• Value: [$X]
• Close Date: [Date]
• Time in Stage: [X days]
• Last Activity: [X days ago] - [Type]
• Engagement Trend: [Increasing/Declining/Stable]

QUALIFICATION STATUS:
• Budget: [✓/⚠/✗] [Status]
• Authority: [✓/⚠/✗] [Decision maker identified?]
• Need: [✓/⚠/✗] [Status]
• Timeline: [✓/⚠/✗] [Status]

STAKEHOLDER MAP:
• Economic Buyer: [Name or "Not engaged"]
• Champion: [Name or "Not identified"]
• Technical: [Name or "Engaged/Not engaged"]
• Users: [Status]

COMPETITIVE CONTEXT:
• Competitors: [Mentioned/None detected]
• Risk Level: [Low/Medium/High]

════════════════════════════════════════════════════
🎯 RECOMMENDED NEXT ACTION
════════════════════════════════════════════════════

[Specific action with reasoning]

BASED ON:
• [X] similar won deals analyzed
• Success pattern: [Key insight]
• Risk mitigation: [What this prevents]

EXECUTION STEPS:
1. [Step 1]
2. [Step 2]
3. [Step 3]

EXPECTED OUTCOME:
• [What this should achieve]
• Target timeline: [X days]

════════════════════════════════════════════════════

Shall I create this activity for you? [Yes/No]
```

### Dataverse Tables Used
| Table | Purpose |
|-------|---------|
| `opportunity` | Current opportunity and similar won deals |
| `account` | Customer context |
| `contact` | Stakeholder information |
| `activitypointer` | Activity history analysis |
| `appointment` | Create recommended meetings |
| `phonecall` | Create recommended calls |
| `task` | Create recommended tasks |
| `email` | Create recommended emails |

### Key Fields Reference
**opportunity:**
- `salesstage` (CHOICE) - Qualify(0), Develop(1), Propose(2), Close(3)
- `stepname` (NVARCHAR) - Current business process step
- `estimatedvalue` (MONEY) - Deal size for matching
- `actualvalue` (MONEY) - Actual revenue (closed deals)
- `estimatedclosedate` (DATE) - Expected close date
- `actualclosedate` (DATE) - When deal closed (won/lost deals)
- `closeprobability` (INT) - Win probability percentage (0-100)
- `budgetstatus` (CHOICE) - No Budget(0), May Buy(1), Can Buy(2), Will Buy(3)
- `need` (CHOICE) - Must have(0), Should have(1), Good to have(2), No need(3)
- `purchasetimeframe` (CHOICE) - Immediate(0), This Quarter(1), Next Quarter(2), This Year(3), Unknown(4)
- `msdyn_opportunityscore` (INT) - AI predictive score (0-100)
- `msdyn_opportunitygrade` (CHOICE) - Grade A(0), B(1), C(2), D(3)
- `msdyn_scorereasons` (MULTILINE TEXT) - JSON with scoring factors
- `msdyn_similaropportunities` (MULTILINE TEXT) - Similar deals data
- `statecode` (STATE) - Open(0), Won(1), Lost(2)
- `statuscode` (STATUS) - In Progress(1), On Hold(2) [Open]; Won(3) [Won]; Canceled(4), Out-Sold(5) [Lost]

**activitypointer:**
- `activitytypecode` (NVARCHAR) - phonecall, email, appointment, task
- `createdon` (DATETIME) - Activity timestamp
- `actualstart`, `actualend` (DATETIME) - Actual activity times
- `regardingobjectid` (LOOKUP) - Polymorphic link to opportunity
- `statecode` (STATE) - Open(0), Completed(1), Canceled(2), Scheduled(3-appointments)

**contact:**
- `accountrolecode` (CHOICE) - Decision Maker(1), Employee(2), Influencer(3)
- `msdyn_decisioninfluencetag` (CHOICE) - Decision maker(0), Influencer(1), Blocker(2), Unknown(3)
- `jobtitle` (NVARCHAR) - For role inference
- `accountid` (LOOKUP → account) - Parent account relationship

**msdyn_opportunitykpiitem (Sales Insights - Relationship Analytics):**
- `msdyn_relationshiphealthscorevalue` (INT) - Health score (0-100)
- `msdyn_relationshiphealthscorestate` (CHOICE) - Good(0), Fair(1), Poor(2)
- `msdyn_emailssent`, `msdyn_emailsreceived` (INT) - Email counts
- `msdyn_phonecallsmade`, `msdyn_phonecallsreceived` (INT) - Call counts
- `msdyn_meetingssent` (INT) - Meeting counts

### Next Best Action Categories

| Stage | Top Actions | Trigger Conditions |
|-------|-------------|-------------------|
| Qualify | Discovery call, Demo | New lead, incomplete BANT |
| Develop | Technical deep-dive, Proof of concept | Requirements gathering needed |
| Propose | Proposal presentation, ROI review | Solution validated |
| Close | Contract review, Executive alignment | Verbal commitment obtained |

### Success Metrics to Track
- Time to next stage after action taken
- Win rate correlation with action types
- Average activities by stage for won vs lost
- Stakeholder engagement depth at each stage

## Examples

### Example 1: Stalled Deal Recommendation

**User says:** "What should I do next on the Contoso Enterprise deal?"

**Actions:**
1. Retrieve opportunity details and activity history
2. Identify current stage (Propose) and last activity (14 days ago)
3. Compare to won deals - identify missing stakeholder engagement
4. Generate prioritized recommendation

**Result:**
```
NEXT BEST ACTION: Schedule Executive Alignment Meeting

CURRENT SITUATION:
- Stage: Propose (14 days, above average)
- Last Activity: Email sent 14 days ago
- Missing: No C-level engagement identified

WHY THIS ACTION:
- Won deals at this stage had 85% executive engagement
- Economic buyer (CFO) not yet contacted
- Similar deals that stalled here won after exec meeting

SUGGESTED APPROACH:
"Hi [Champion], I'd like to connect with [CFO Name] to discuss how our solution aligns with your strategic priorities. Could you facilitate an introduction?"
```

### Example 2: Early Stage Deal Coaching

**User says:** "How do I move the Fabrikam deal forward?"

**Actions:**
1. Analyze current qualification status
2. Identify BANT gaps
3. Recommend discovery activities

**Result:**
```
NEXT BEST ACTION: Schedule Discovery Call

GAPS IDENTIFIED:
- Budget: Not confirmed
- Timeline: Unknown

RECOMMENDED QUESTIONS:
1. "What's your budget range for this initiative?"
2. "When do you need a solution in place?"

SCHEDULE: Suggested times sent to contact
```

### Example 3: Close Stage Acceleration

**User says:** "What's blocking the Alpine deal from closing?"

**Actions:**
1. Analyze close stage opportunity
2. Check for missing elements vs. won deals
3. Identify potential blockers

**Result:**
```
POTENTIAL BLOCKERS IDENTIFIED:
1. No legal contact engaged (90% of won deals had legal by now)
2. Procurement not in activity history
3. Close date is Friday but no contract sent

RECOMMENDED ACTIONS:
1. Request introduction to procurement contact
2. Send contract for review today
3. Offer implementation timeline to address concerns
```

## Troubleshooting

### Error: Opportunity not found
**Cause:** Invalid opportunity ID or deal has been closed
**Solution:**
- Search by opportunity name instead
- Check statecode to see if deal is already won/lost
- Verify user has access to the record

### Error: No similar won deals found
**Cause:** Unique deal characteristics or limited history
**Solution:**
- Expand matching criteria (industry, size range)
- Use generic stage-based best practices
- Increase date range for historical comparison

### Error: Activity history incomplete
**Cause:** Activities not linked to opportunity
**Solution:**
- Query activities for related account as well
- Check team member activities (not just owner)
- Advise user on proper activity linking