---
template: "page.peb"
title: "Decision Overlay Pattern"
displayName: "Decision Overlay Pattern"
description: "A reusable Salesforce pattern for attaching AI next action, confidence, and rationale fields to operational records."
category: "patterns"
contentType: "reference"
audience: "developer"
tags: "patterns,salesforce,ai,decision-support,governance"
section: "patterns"
seoTitle: "Decision Overlay Pattern"
seoDescription: "A reusable Salesforce pattern for attaching AI next action, confidence, and rationale fields to operational records."
---

## Decision Overlay Pattern

The Decision Overlay Pattern adds AI decision-support fields directly onto an existing Salesforce record so users can review a recommended next action, its confidence level, and the reasoning context that produced it.

This is an overlay pattern, not a separate object model. It fits records that already represent work, risk, ownership, or progression, such as Leads, Opportunities, Cases, approvals, work orders, and intake records.

## Intent

Expose AI guidance on the same record where work happens so that recommendations are reviewable, governable, and easy to tune over time.

## Problem

AI outputs are difficult to operationalize when they only appear as transient chat messages or opaque automations. Users cannot easily tell what the system recommends, how strongly it believes that recommendation, or what knowledge, memory, or rules influenced the output.

Without those signals, administrators also lose the feedback loop needed to improve the agent. Bad or inconsistent recommendations get noticed late, and the reason for the failure is harder to diagnose.

## Structure

The pattern overlays three conceptual fields onto an existing business record:

- A next action field that tells the user what the AI recommends doing next.
- A confidence field that tells the user how strongly the system stands behind the recommendation.
- A rationale field that summarizes the rules, knowledge, memory, or record context that influenced the result.

Together, the three fields make the recommendation inspectable instead of implicit.

## Participants

- Business record: The operational Salesforce record receiving the AI guidance, such as a Lead, Opportunity, Case, or task-driving custom object.
- Decisioning agent: The AI process that evaluates record context and proposes the next action.
- Knowledge and rules layer: The org-specific instructions, reference knowledge, memory, and decision rules used by the agent.
- Human operator: The seller, service rep, manager, or analyst who reviews the recommendation and decides whether to act on it.
- System administrator: The owner who tunes prompts, knowledge, field mappings, thresholds, and workflow behavior based on observed outputs.

## Runtime Flow

1. A record reaches a state where AI guidance is useful.
2. The agent evaluates the record using current data, org knowledge, memory, and operating rules.
3. The system writes a recommended next action, a confidence score, and a rationale summary onto the record.
4. A user or downstream workflow reviews the overlay before acting.
5. Low-confidence, contradictory, or weak recommendations are used as tuning signals for admins.

## Salesforce Reference Implementation

Use generic conceptual names in the architecture, then implement them with explicit Salesforce fields. The following field set is a strong default for many orgs:

| Purpose | Default field | Type | Notes |
| --- | --- | --- | --- |
| Next action | `AI_Next_Action__c` | Rich Text Area (32768) | Stores the recommended next step in business language. |
| Confidence | `AI_Confidence_Score__c` | Number(2,0) | Uses a `0-5` scale where `0` means no confidence and `5` means highest confidence. |
| Rationale | `AI_Rationale__c` | Rich Text Area (1024) | Summarizes the rules, memory, knowledge, or context that influenced the result. |

The exact API names can vary by org, but the pattern works best when these three signals are always produced together.

## Interpreting the Signals

The value of the pattern is not just the recommendation itself. It is also the shape formed by the three fields together.

| Signal pattern | Typical meaning | Admin response |
| --- | --- | --- |
| Strong next action with low confidence | The system sees a possible path but lacks enough instruction or context to recommend it reliably. | Tighten prompts, improve record context, or expand knowledge coverage. |
| Weak or generic next action with high confidence | The agent may be overconfident, or the scoring rubric is too coarse. | Recalibrate confidence guidance and review prompt examples. |
| No next action with a useful rationale | The system is correctly surfacing a gap such as missing inputs, approvals, or knowledge. | Fix the upstream data or add missing instructions. |
| Good next action with clear rationale and mid-to-high confidence | The workflow is stabilizing and can be monitored for broader rollout. | Measure workflow-specific accuracy before increasing automation. |

In mature implementations, teams often see the recommendation become more reliable over time, but that must be measured per workflow. Confidence should never be treated as proof of correctness.

## Applicability

Use this pattern when an AI system is advising users on what to do next, especially on records where timing, ownership, compliance, or customer outcome matters.

Common fits include:

- Lead qualification and routing
- Opportunity progression and deal strategy
- Case triage and escalation
- Approval reviews
- Work order dispatch
- Intake and exception handling queues

## Consequences

Benefits:

- Makes AI recommendations visible where users already work.
- Creates a practical tuning loop for admins and solution owners.
- Improves auditability by preserving both recommendation and explanation context.
- Supports phased rollout from assistive guidance toward selective automation.

Tradeoffs:

- Adds fields and layout complexity to operational records.
- Requires governance for when and how the overlay is refreshed.
- Can create false certainty if confidence scoring is poorly defined.

## Anti-patterns

- Do not auto-execute high-impact actions solely because the confidence score is high.
- Do not treat the rationale field as raw chain-of-thought; store a concise business-safe explanation instead.
- Do not assume one confidence threshold is appropriate for every object, team, or workflow.
- Do not write the next action without also writing confidence and rationale, because the overlay loses most of its governance value when one of the signals is missing.

## Related patterns

- [Model View Agentic Controller (MVAC) Pattern](/well-architected/Model_View_Agentic_Controller.html)
- [Data Context Definition (DCD)](/agents/DataContextDefinition.html)