Scenario Builder

The Scenario Builder is the heart of ClientCoach AI’s customization engine. It allows trainers, admins, and simulation designers to create dynamic, realistic conversation flows tailored to different goals, customer personas, and skill development areas.

🧩 How It Works

The simulation system is built around scenarios, which are structured into phases, and evaluated using aspects. Each component plays a role in controlling the conversation flow and how performance is measured.

🔷 1. Scenarios

A scenario defines the overall context of the simulation.

Field	Description
name	The title of the scenario (e.g., “Upset Customer About Downtime”)
description	A short summary of what the scenario is about
context	Rich background that sets the stage for the agent (e.g., business type, customer history)
initial_prompt	The first message from the AI customer that kicks off the conversation

🔶 2. Phases

Each scenario is broken into phases that mimic stages of real-world customer conversations, like:

• Introduction

• Discovery

• Value Proposition

• Objection Handling

• Closing

Field	Description
name	The name of the phase (e.g., "Objection Handling")
scenario_id	Links this phase to its scenario
system_prompt	Instructional guidance to steer the AI customer’s behavior in this phase
on_success	Next phase to move to if the agent performs well
on_failure	Alternate path if the agent misses key goals or triggers red flags

🟢 3. Aspects

Each phase includes aspects used by the evaluator to score performance. These represent the expectations of that phase.

Field	Description
phase_id	Links the aspect to its parent phase
name	Describes the specific behavior or insight expected (e.g., “Introduces Copilot clearly”)
type	One of: critical, optional, or red_flag

Aspect Types

• Critical: Must be met to succeed in the phase

• Optional: Adds value but isn’t mandatory

• Red Flag: Should be avoided; will penalize performance if triggered

---

🧑‍💻 Building Scenarios

You can define scenarios in two ways:

1. Admin Web Interface Use the in-app scenario builder (coming soon) to define each part with an intuitive UI.

2. Supabase Dashboard Directly manage scenario, phase, and aspect entries through your Supabase tables.

---

🔄 Phase Transitions Logic

Each phase includes conditions for transition. The system evaluates:

• Whether all critical aspects are met

• Whether any red flags were triggered

• Then determines whether to continue the current path or pivot

Example:

Phase	On Success →	On Failure →
Discovery	Value Proposition	Closing
Objection Handling	Closing	End

---

✅ Best Practices

• Keep scenarios realistic with detailed context

• Use critical aspects sparingly but meaningfully

• Ensure each system prompt aligns with the customer’s role and tone

• Review transition logic for circular loops or dead ends