Next-best-action engine

in industry terms

A next-best-action engine is a policy: given a lead's state, which action now.

CRM and marketing platforms call this next best action or next best offer; in machine learning it's a decision policy, and with logged odds it becomes a contextual bandit. The difference from a static sequence: the order of steps isn't fixed, it's chosen each time from what is allowed and likely to work.

how it works

Six stages, run for every eligible lead.

The output is today's ranked list for the founder. Everything in between is logged so the ranking can be judged and improved later.

1. Candidates — possible moves
2. Features — frozen per lead
3. Score — value × chance
4. Policy filter — caps, never
5. Rank + cap — daily limit
6. Log — menu, pick, odds
7. Founder — act, skip, snooze blocked
8. Blocked — rule logged

1 · candidates — What could happen next · The next step of an active sequence, starting a play whose trigger fits, waiting, stopping, answering them.

2 · features — Frozen at decision time · Tier, trigger, signal age, fit lines, replies so far, days since last touch, channel open.

3 · score — Expected value · Chance it gets a reply or a join, times what that's worth, minus founder minutes. Rules today; a learned model later.

4 · policy — Hard limits · The contact policy removes any move it doesn't allow, and logs why.

5 · rank — Daily cap · Highest first, people waiting first, overflow waits for tomorrow in rank order.

6 · log — The whole menu · Candidates with scores, the pick, its probability, and later the outcome via the touch_id.

the score

A transparent v1, then a learned v2.

Phase 1 ranks with rules. The proposal below makes the rule explicit so it can be logged and later replaced by a model trained on the outcomes it produced.

score(move, lead) = p_success(move, lead) · value(move) − cost(move) / founder_minute_value

p_success v1: lookup by (move type, tier, signal age bucket) v2: reply-propensity model
value join = 1.0 · positive reply = 0.3 · brief opened = 0.2 · public reply = 0.05
cost founder minutes for the move
boosts waiting on you: rank first · fresh (< 24 h): ×1.5 · stacked signals: ×1.2

exploration: with probability ε = 0.1, pick uniformly among allowed moves; log probability either way

the object

The move, as logged.

One move record per lead per decision, with the whole menu.

one record, as data

{
 "move_id": "move_…",
 "lead_id": "lead_…",
 "decided_at": "2026-10-21T12:00:00Z",
 "scorer_version": "nba.v1",
 "features": {
 "tier": "Hot",
 "trigger": "public_pain",
 "signal_age_h": 20,
 "replied": true,
 "dms_sent": 0
 },
 "candidates": [
 {
 "move": "answer_them",
 "score": 0.82
 },
 {
 "move": "dm_offer",
 "score": 0.41
 },
 {
 "move": "wait",
 "score": 0.05
 },
 {
 "move": "stop",
 "score": 0
 }
 ],
 "blocked": [],
 "chosen": "answer_them",
 "propensity": 0.925,
 "founder_action": "edited",
 "touch_id": "touch_…",
 "outcome": null
}

the catalog

Thirteen move types the engine chooses between.

Reach moves contact the person; convert moves make the ask; hold moves wait or hand work to the founder; end moves stop or exclude.

illustrative example

One lead, one morning.

The scores are invented to show the shape.

state — Hot tier, posted the pain 20 hours ago, you replied in the thread yesterday, they answered with a question

candidates — answer them 0.82 · DM with the brief 0.41 · wait 0.05 · stop 0.00

policy — DM allowed (no DM sent yet); nothing blocked

chosen

answer them, propensity 0.93 (ε = 0.1, 4 allowed moves)

People waiting on you rank first.

founder — edits the draft and sends; the touch_id joins tomorrow's reply to this move

failure modes

What goes wrong, and how to catch it.

How each one shows up, and the check that catches it before it costs a week.

data to capture

Record it so a model can learn from it later.

Follows the guide's eight data-spine rules: log the decision, version what decided, freeze the inputs, keep the negatives, log the odds, treat every human touch as a label, keep one chain of ids, keep the raw.

related pages

Where this connects.